Contacts API reference

Contact objects represent your contacts stored in Notifuse. There is only one method to insert and update a contact: upsert. If a contact doesn't exist yet, it will be inserted, otherwise updated.

Documented endpoints:

contacts.upsert

Curl Node PHP

The contact object

A contact object has 2 IDs, an internal Notifuse id, and it's external id. The external id is the one used by your own database. You should never have to use the Notifuse id...

id string	Notifuse internal id.
externalId string	External id, the one you will use to upsert a contact.
project string	Project id.
profile object	JSON object of all stored data in your contact profile.
stats object	Monthly stats of messages received by the contact.
createdAt string: ISO date	Creation date.


{
  "id": "572d923d09fd33bb9115c3af",
  "externalId": "123",
  "project": "my-project",
  "profile": {
    "id": "123",
    "firstName": "Justin",
    "lastName": "Bieber",
    "email": "justin.bieber@yopmail.com"
  },
  "stats": {
    "2016": {
      "10": 3,
      "11": 4
    }
  },
  "createdAt": "2016-10-22T04:31:13.589Z"
}

contacts.upsert

Insert / update an array of 50 contacts max.

Request

JSON body
id required string	Your external id.
profile optional object	JSON object containing database operations to apply on the profile.
createdAt optional string	ISO 8601 date string to use as the creation date when the contact is upserted for the first time. Example: 2016-02-04T22:44:30.652Z

Response

statusCode integer	HTTP status code returned.
success boolean	true or false.
inserted array of strings	Array of inserted ids.
updated array of strings	Array of updated ids.
failed array of strings	Array of failed ids.

Example Request


curl -X POST \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
        "contacts": [{
          "id": "123",
          "profile": {
            "$set": {
              "firstName": "Justin",
              "lastName": "Bieber",
              "email": "justin.bieber@yopmail.com"
            },

            "$push": {
              "tags": "customer"
            },

            "$inc": {
              "totalOrders": 1
            }
          },

          "createdAt": "2016-02-04T22:44:30.652Z"
        }]
      }' \
  https://api.notifuse.com/v2/contacts.upsert


var Notifuse = require('notifuse'),
    client = new Notifuse.Client(API_KEY);

client.contacts.upsert([
    {
      id: "123",
      profile: {
        $set: {
          firstName: "Justin",
          lastName: "Bieber",
          email: "justin.bieber@yopmail.com"
        },

        $push: {
          tags: "customer"
        },

        $inc: {
          totalOrders: 1
        }
      },
      createdAt: "2016-02-04T22:44:30.652Z"
    }
  ], function(error, response){

});


use Notifuse\NotifuseClient;

$client = new NotifuseClient($API_KEY);

$contact = array(
  'id' => '123',
  'profile' => array(
    '$set' => array(
      'firstName' => 'John',
      'lastName' => 'Rambo',
      'email' => 'justin.bieber@yopmail.com'
    ),
    '$push' => array(
      'tags' => 'customer'
    ),
    '$inc' => array(
      'totalOrders' => 1
    )
  ),
  'createdAt' => '2016-02-04T22:44:30.652Z'
);

try {
  $response = $client->contacts->upsert(array($contact));
} catch (Exception $e){
  // handle error
}

Example Response


array(
  'statusCode' => 200,
  'success' => true,
  'inserted' => ['123'],
  'updated' => [],
  'failed' => []
)


{
  "statusCode": 200,
  "success": true,
  "inserted": ["123"],
  "updated": [],
  "failed": []
}