ChatGPT & AI: We’re incorporating AI into engageSPARK.

Create, Update, and Delete Phone Numbers via API

 

Do you want to easily create, update, and delete phone numbers in your engageSPARK account? engageSPARK’s super fast and powerful contacts API allows you to do just that. For now, this article will show you how to create or add contacts to your account – updating and deleting contacts will be added soon.

Create Contacts

Update Contacts

Delete Contacts

 

Create Contacts API

HTTP Method & Headers

The HTTP method is POST using the URL below:

https://api.engagespark.com/v1/organizations/{orgid}/contacts/

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {apikey}
Content-type application/json

 

Request Body Definition

Below are the only details you need to provide in order for you to successfully create contacts using the Contacts API:

Key Description Data Type Required Example
firstName This is your contact’s first name. String Optional “Anne”
lastName This is your contact’s last name. String Optional “Jones”
fullPhoneNumber

This is your contact’s phone number in international format with no leading “+” sign (E164 format).

Note: If you decide to use fullPhoneNumber in your API’s request body, there’s no need to include phoneNumber and phoneNumberCountry in your request.

String Yes, if not passing phoneNumber & phoneNumberCountry “639123456789”
phoneNumber

This is your contact’s phone number in local format that can have a leading “0”, spaces, and dashes.

Note: If you decide to use phoneNumber in your API’s request body:
— you need to include phoneNumberCountry in your request.
— there is no need to include fullPhoneNumber.

String Yes, if not passing fullPhoneNumber “09123456789” or
“09-123-456-789” or
“09123 456 789”
phoneNumberCountry This is a 2-letter country code which will be used by the system to determine which country the phoneNumber belongs to. String Yes, if passing phoneNumber “PH”
language You can use this to set the language your contact speaks. String Optional “English”
customFields You can use this to set additional data into the existing customFields in your account. Custom fields can be any fields you added in your engageSPARK account’s contacts page like: Age, Gender, Address, Educational Attainment, etc. To be able to use this, you need to know the customFields ID of your custom fields. (To get your list of customFields, with IDs and values, make a GET request to https://api.engagespark.com/v1/organizations/{orgid}/customfields/ – as always, replace {orgid} with your orgID.) object with id:value Optional “customFields”: {
“1234”: “40”,
“1235”: “Female”
}
groups You can use this to add the contact to one or more groups. (To get your list of group IDs and names, make a GET request to https://api.engagespark.com/v1/organizations/{orgid}/groups/ – as always, replace {orgid} with your orgID.) array of integers Optional “groups” : [123,124]

Sample JSON (using fullPhoneNumber):

{
"firstName": "Anne",
"lastName": "Jones",
"fullPhoneNumber": "639123456789",
"language": "English",
"customFields": {
"1234": "40",
"1235": "Female"
},
"groups": [123,124]
}

 

Sample JSON (using phoneNumber):

{
"firstName": "Anne",
"lastName": "Jones",
"phoneNumber": "09123 456 789",
"phoneNumberCountry": "PH",
"language": "English",
"customFields": {
"1234": "40",
"1235": "Female"
},
"groups": [123,124]
}

 

Response Body Definition

Below are the details that will be returned after every create contacts API request:

Key Description Data Type Example
id This is a system-generated ID for every new successful contact created. Integer
“987654”
firstName This is your contact’s first name. String
“Anne
lastName This is your contact’s last name. String “Jones”
fullPhoneNumber This will be returned if you used fullPhoneNumber for your contact’s phone number.
Otherwise, phoneNumber and phoneNumberCountry will be returned.
String “639123456789”
phoneNumber This will be returned along with phoneNumberCountry if you used phoneNumber for your contact’s phone number.
Otherwise, fullPhoneNumber will be returned.
String “0.02”
phoneNumberCountry This will be returned if you used phoneNumber for your contact’s phone number.
Otherwise, fullPhoneNumber will be returned.
String
“PH”
language If you specified a language in your request, this will be returned by the system. String “English”
createdAt Shows the date and time when the contact was successfully created. JSON String “2020-12-24T21:56:16.944087Z”
customFields The custom fields you specified in your request. object with id:value “customFields”: {
“1234”: “40”,
“1235”: “Female”
}
groups The groups you specified in your request. array of integers “groups”: [123,124]

Sample JSON Response:

{
"id": 987654,
"firstName": "Anne",
"lastName": "Jones",
"fullPhoneNumber": "639123456789",
"language": "English",
"createdAt": "2020-12-24T21:56:16.944087Z",
"groups": [],
"customFields": {
"1234": "40",
"1235": "Female"
},
"groups": [123,124]
}

List of Possible HTTP Status Codes

Success:

200 – everything’s fine.

Failed:

400 – there’s something wrong with the request. Please see the error field in the response body.

401 – authentication problems.

500 – engageSPARK internal service error.

Update Contacts API

HTTP Method & Headers

The HTTP method is PUT using the URL below:

https://api.engagespark.com/v1/organizations/{orgid}/contacts/{id}/

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {apikey}
Content-type application/json
  • Replace {orgid} with your actual organization ID which you can find here: Account (Avatar icon) > Organization > Info > Organization ID https://app.engagespark.com/account/organization/info. Don’t forget to remove the curly braces { }.
  • Replace {API_KEY} with your actual API Key which you can find here: Account (Avatar icon) > Profile > Info > API Key https://app.engagespark.com/account/profile/info. Don’t forget to remove the curly braces { }.
  • Replace {id} with the contact ID created on Create Contacts API (on example above it would be “id”: 987654)

 

Request Body Definition

The details you need to provide to successfully update contacts using the Contacts API are the same as the ones used to create contacts (see above)

 

 OR

 

Provide only the details of the information you want to change 

Sample JSON (if you only wanted to change the language):

{
"language": "Spanish"
}

 

Sample JSON (if you wanted to change all previous information):

{
"firstName": "Annie", 
"lastName": "Jones-Smith", 
"phoneNumber": "19123456789", 
"phoneNumberCountry": "US", 
"language": "Spanish", 
"customFields": { 
"5678": "41", 
"1236": "Other" 
}, 
"groups": [125,126] 
}

 

Response Body Definition

The details that will be returned after every update contacts API request are the same as the details from create contacts API (see above):

List of Possible HTTP Status Codes

Success:

200 – everything’s fine.

Failed:

400 – there’s something wrong with the request. Please see the error field in the response body.

401 – authentication problems.

500 – engageSPARK internal service error.

Delete Contacts API

HTTP Method & Headers

The HTTP method is DELETE using the URL below:

https://api.engagespark.com/v1/organizations/{orgid}/contacts/{id}/

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {apikey}
Content-type application/json
  • Replace {orgid} with your actual organization ID which you can find here: Account (Avatar icon) > Organization > Info > Organization ID https://app.engagespark.com/account/organization/info. Don’t forget to remove the curly braces { }.
  • Replace {API_KEY} with your actual API Key which you can find here: Account (Avatar icon) > Profile > Info > API Key https://app.engagespark.com/account/profile/info. Don’t forget to remove the curly braces { }.
  • Replace {id} with the contact ID created on Create Contacts API (on example above from the Create Contacts API it would be “id”: 987654)

 

Request Body Definition

Below are the only details you need to provide in order for you to successfully delete contacts using the Contacts API:

Key Description Data Type Example
id This is a system-generated ID for your contact  Integer
“987654”

 

Sample JSON:

 

No body is necessary for this request.  

 

Response Body Definition

An empty body will be returned after every successful delete contacts API request:

Sample JSON Response:

 

{}

 

List of Possible HTTP Status Codes

Success:

200 – everything’s fine.

Failed:

400 – there’s something wrong with the request. Please see the error field in the response body.

401 – authentication problems.

404 – if the contact is not found.

500 – engageSPARK internal service error.

 

Have questions or need a little extra help?