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/

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

You’ll need to set the following HTTP Headers:

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 “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 “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 “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. (we’ll have a separate API for getting customFields ID). object with id:value Optional “customFields”: {
“1234”: “40”,
“1235”: “Female”
}

Sample JSON (using fullPhoneNumber):

{
"firstName": "Anne",
"lastName": "Jones",
"fullPhoneNumber": "639123456789",
"language": "English",
"customFields": {
"1234": "40",
"1235": "Female"
}
}

 

Sample JSON (using phoneNumber):

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

 

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”
}

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"
}
}

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.

Have questions or need a little extra help?

Get in touch with us via:

facebook-logo    messenger-logo    twitter-logo

Or