Adding and Updating Contacts via the API

Charles Parsons

October 20, 2022 09:55

You can easily add or modify contacts records in Message by making a POST to this endpoint:

POST https://theseus-api.signalvine.com/v2/programs/{program id}/participants

The request payload that you'll send has a few fairly-straightforward properties that will need to be included:

JSON Body

{ 
 "program": "{program_id}",
 "options": {
 "new": // either add or ignore,
 "mode": // either row or tx,
 "existing": // either ignore or an array of field names,
 "absent": "ignore"
 }, // see below 
 "participants": "" // The CSV file sent as a JSON encoded string 
}

Here's the breakdown of how the payload is constructed:

program: the program ID of the program you're working in. If you don't know the program ID, you can find it in Message in Programs -> Program Settings.

options: this object instructs the API on how you'd like the contact data processed. Each of the following fields are required:

new - how do you want Message to handle new records it finds?
- add: any contacts in the CSV that don't exist in Message will be added to the program
- ignore: any contacts in the CSV that don't exist in Message will be ignored
existing - how do you want Message to update existing records?
- [...]: to update existing contacts, include the names of the fields that should be updated in an array; this may include all fields but doesn't need to.
- ignore: any contacts in the CSV that also exist in Message will be ignored
mode - how do you want Message to handle errors?
- row: process as many rows as possible from the CSV and respond with all errors that occurred during processing (no rows will be added if there are more than total 1,000 errors).
- tx: process all rows in a transaction, only commit changes to the program if the CSV contains no errors.
absent - how do you want Message to process missing records?
- ignore: as of now, there are no options for automatically removing absent contacts, so this value must always be set to ignore.

Example (ignore new, update existing)

{ 
 "program": "ed1b9efb-0ccf-4ea0-9585-0d7e57f28869",
 "options": {
     "new": "ignore",
     "existing": ["first_name","last_name","active"],
     "mode": "row",
     "absent": "ignore"
 },
 "participants": "signalvine_id,first_name,last_name,active\n33a58d8b-27cb-11e8-ad0a-0ab427fa565c,Charles,Parsons,true"
}

In the above example, a single contact will have their first name, last name and active status updated. If the contact is not found, it will not be added. Note the JSON-encoded CSV structure with \n representing new lines in the file.

What happened to my update?

If your API POST is accepted, you will receive a 202 response back. The actual process to add or update contacts is asynchronous however, so you will need to poll the API to see if there were any errors in your import. In the response header, you will find a Location endpoint that will give you the status of the command that you sent.

We recommend requesting status 2 seconds after your initial POST, and then every 2 seconds for the next 30 seconds and an incremental back-off policy after that to give the system time to complete your command. The vast majority of requests will be complete before the first poll, but processing can take time if the import set is very large or there are many batches running.

If the command hasn't been completed, you will receive a response that looks like this:

{
 "commandId": <command id>,
 "name": <name of command issued>
 "from": <the person / token that issued the command>
 "created": <time the server received the command>
 "error": false
 "complete": false
}

If the command has completed successfully, the response will be:

{
  "commandId": <command id>,
  "name": <name of command issued>
  "from": <the person / token that issued the command>
  "created": <time the server received the command>  "message"
  "complete": true,
  "error": false,
  "message": <for import a JSON object describing the results>
}

If the command completed with errors, the response will be:

{
  "commandId": <command id>,
  "name": <name of command issued>
  "from": <the person / token that issued the command>
  "created": <time the server received the command>
  "complete": true,
  "error": true,
  "message": <for import a JSON object describing the errors>
  "trace": <stack trace used for debugging>
  "processor": <the name of the processing agent>
}

But I didn't get a 202 - I got an Unauthorized error

An Unauthorized error is almost always a problem with the encrypted token used for authentication. Confirm that the payload body is encoded correctly when the token is generated and try again.