Notivize Partner Endpoint API Specifications

When setting up your Amplitude Integration with Notivize you must define an endpoint (secured by an API key) that will be used to retrieve all the information needed for sending a notification. In exchange for Amplitude cohort user ids, you will return recipient information and context variables used in the template of your notification.

Here is the API Specification to build your endpoint:

API Headers

Notivize will send the following headers when making a POST request against your API endpoint:

Name	Values
Authorization	Basic {{api_key}}
Content-Type	application/json
Accept	application/json

API Body

Notivize will send the following JSON body:

Name	Value(s)
user_ids	array[string]

Example

{
  user_ids: [
    "5236489239",
    "8026404105",
    "6557437082",
    "3739884942",
    "0958913505",
    "3911793580",
    "3937292296",
    "1626624548",
    "3752577837",
    "6236286138",
    ...
  ]
}

API Response (expected from your API endpoint)

Notivize expexcts a JSON response containing a list where each item has the following fields:

Name	Value(s)
to	To: object
variables	Variables: object

To

Notivize supports 3 channels with Amplitude (Email, SMS, and Push Notification). You need to set the key/value pair for the channel matching your notification channel. If you send notifications to different channels, you may set all the key/value pairs for which you have data.

Channel	Expected Key
Email	"email"
SMS	"phone"
Push Notification	"token"

{
  "email": "[email protected]"
}

{
  "email": "[email protected]",
  "phone": "+13256764532",
  "token": "5684874357487068"
}

Variables

The variables object contains the context variables for the notification template, as well as variables used to evaluate rules and a unique_id. Any extra variables (not used in template or rules) will be ignored. If you don't provide a unique id, we'll use the first non-null value found in the "to" object in order to prevent sending the same notification twice to the same recipient.

{
  "first_name": "Fake",
  "last_name": "Name",
  "age": 30,
  "unique_id": "[email protected]"
}

{
  "first_name": "Fake",
  "last_name": "Name",
  "age": 30,
  "birthday": "2021/01/01",
  "cart_count": 12,
  "last_visited": "2021/01/01T10:10:00-07:00"
}

Scenario

Notification

<body>
  <h1>Hello {{first_name}}</h1>
  <p>Thanks for reviewing {{review_count}} products.</p>
</body>

Hi {{first_name}} 👋🏻
Thanks for installing the Acme app!

You wrote {{review_count}} reviews, one more to go before getting a promo code!

Query from Notivize to your endpoint

curl -X POST "https://partner.com/amplitude/user_info" \
     -H "Authorization: Bearer 1234-xxxx-zzzz" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     --data '{"user_ids": ["1234", "5678", "9101"]}'

Response

[
  {
    "to": {
      "token": "1234",
      "email": "[email protected]",
      "phone": null
    },
    "variables": {
      "unique_id": "user_id_1",
      "first_name": "fake name 1",
      "review_count": 3
    }
  },
  {
    "to": {
      "token": "5678",
      "email": "[email protected]",
      "phone": "+13031234567"
    },
    "variables": {
      "unique_id": "user_id_2",
      "first_name": "fake name 2",
      "review_count": 15
    }
  },
  {
    "to": {
      "token": null,
      "email": null,
      "phone": "+13031234567"
    },
    "variables": {
      "unique_id": "user_id_3",
      "first_name": "fake name 3",
      "review_count": 1000
    }
  }
]