REST API

You can use the Outbound REST API to send user and event data to Zendesk Connect, or to update other Connect settings.

This document covers the following topics:

Authenticating requests

To authenticate API requests, include a 'X-Outbound-Key: PRIVATE_KEY' header in each request. Example:

curl https://api.outbound.io/v2/identify \
  -d '{"user_id": "agentsmith@example.com"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST

For more information, see Authentication in the introduction.

Identify a user

  • POST https://api.outbound.io/v2/identify
  • POST https://api.outbound.io/v2/identify/batch

Adds or updates one or more user records in the Connect account.

The identify endpoint accepts a JSON user object. See User properties.

The batch endpoint accepts a list of up to 100 user objects, with a total payload size of up to 8 MB.

Using cURL

identify

curl https://api.outbound.io/v2/identify \
  -d '{
        "user_id": "agentsmith@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "email": "agentsmith@example.com"
      }' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v

identify/batch

curl https://api.outbound.io/v2/identify/batch \
  -d '[{
         "user_id": "user1",
         "email" : "test1@test.com",
         "attributes" : {"custom attribute": "custom value" }
       },
       {
         "user_id": "user2",
         "email" : "test2@test.com",
         "attributes" : {"custom attribute": "custom value" }
       }]' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v
Example response
HTTP/1.1 200 OK

Track an event

  • POST https://api.outbound.io/v2/track
  • POST https://api.outbound.io/v2/track/batch

Sends one or more events to Connect.

The track endpoint accepts a JSON event object. See Event properties.

The batch endpoint accepts a list of up to 100 event objects, with a total payload size of up to 8 MB.

Each event must be associated with a user record in Connect so that Connect can send a message to the user in response to the event. You can only send events specifying a user if the user has been identified in Connect. See Identify users above.

You can also update a user's information in Connect when sending an event. See Updating a user with an event.

Using cURL

track

curl https://api.outbound.io/v2/track \
  -d '{"user_id": "4512345", "event": "checkOut"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v

track/batch

curl https://api.outbound.io/v2/track/batch \
  -d '[{"user_id": "4512345", "event": "checkOut"},
       {"user_id": "5632454", "event": "confirmPurchase"}]' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v
Example response
HTTP/1.1 200 OK
Updating a user with an event

In some cases, you might need to update a user's information in Connect with the event sent. For example, the event might consist of the user updating their email in their user profile.

To update a user when sending an event, replace the user_id property in the track event request body with a user object. Example:

curl https://api.outbound.io/v2/track \
  -d '{"user": {
        "user_id": "4512345",
        "email": "janedoe@example.com"
      },
      "event": "updateEmail"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v

You can also use the user object in the track/batch endpoint.

Disable Push Notifications to Mobile Device

  • POST https://api.outbound.io/v2/apns/disable
  • POST https://api.outbound.io/v2/gcm/disable

Disables an Apple Push Notification service (APNs) or Google Cloud Messaging (GCM) push notification device token for an individual user.

You associate a device token with a user with apns or gcm attribute when identifying the user. See the Identify User endpoint.

JSON format
Name Type Mandatory Description
user_id string yes The Connect id of the user. See Users
token string yes APNs or GCM token to disable. Not required if the 'all' property is set
all boolean no If true, disables all tokens for the user
Using cURL

apns/disable

curl https://api.outbound.io/v2/apns/disable \
  -d '{"user_id": "4512345",
       "token": "5311839E96AF71A22745D0FB50DED665E0E882"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v

gcm/disable

curl https://api.outbound.io/v2/gcm/disable \
  -d '{"user_id": "4512346",
       "token": "5311839E96AF71A22745D0FB50DED665E0E883"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v
Example response
HTTP/1.1 200 OK

Unsubscribe User from All Campaigns

POST https://api.outbound.io/v2/unsubscribe/all

Unsubscribes a specified user from all Connect campaigns. Connect won't send messages to the user even if the user meets the campaign criteria for sending a message.

Note: If the "Allow unsubscribes and apply unsubscribe list" checkbox is not selected in the Edit campaign page in Connect, messages will still be sent to unsubscribed users.

JSON format
Name Type Mandatory Description
user_id string yes The Connect id of the user. See Users
Using cURL
curl https://api.outbound.io/v2/unsubscribe/all \
  -d '{"user_id": "4512345"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v
Example response
HTTP/1.1 200 OK

Unsubscribe User from Selected Campaigns

POST https://api.outbound.io/v2/unsubscribe/campaigns

Unsubscribes a specified user from one or more Connect campaigns. Connect won't send messages to the user even if the user meets the campaign criteria for sending a message.

You must specify ids for the campaigns. You can find the id of each campaign by opening the Campaigns page in Connect and selecting each campaign. The campaign id is displayed in the URL. Example:

https://dashboard.outbound.io/dashboard/campaigns/592ef8dfcdb38a09f6a7745a

JSON format
Name Type Mandatory Description
user_id string yes The Connect id of the user. See Users
campaign_ids array yes A list of Connect campaign ids
Using cURL
curl https://api.outbound.io/v2/unsubscribe/campaigns \
  -d '{"user_id": "4512345",
       "campaign_ids": [
         "592ef8dfcdb38a09f6a7745a",
         "2958a9f6afed7fe6b7f8defd"
        ]
      }' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v
Example response
HTTP/1.1 200 OK

Re-subscribe User to All Campaigns

POST https://api.outbound.io/v2/subscribe/all

Re-subscribes a specified user to all Connect campaigns.

JSON format
Name Type Mandatory Description
user_id string yes The Connect id of the user. See Users
Using cURL
curl https://api.outbound.io/v2/subscribe/all \
  -d '{"user_id": "4512345"}' \
  -H 'X-Outbound-Key: PRIVATE_KEY' \
  -X POST -v
Example response
HTTP/1.1 200 OK

Internal Errors

If any of the above endpoints encounters an error it cannot recover from it will return a 500 error code. Please retry the request after a short delay.

Example Error response
HTTP/1.1 500 Internal Server Error