Introduction
Channels
Templates
Contacts
Messages
API
public
beta
Docs Contact Login

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:
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": []
}