Understand how to use of Netcore Contact APIs (V5).
The Contacts API V5 allows you to manage contact data in Netcore CE. You can use these APIs to create, search, update, and delete contacts, as well as search contacts within an audience.
What is a ContactA contact is an individual user or customer whose information is stored in Netcore CE.
A contact can contain information such as their identity, email address, mobile number, and other attributes. Contacts can also be associated with audiences for segmentation and targeting.
Depending on the information available for a contact, you can work with different contact types, such as identified and anonymous contacts.
Types of Contact
| Contact Type | Description |
|---|---|
| Anonymous Contacts | Contacts whose primary identifiers (like email or phone) are not available. These contacts can still be targeted using limited channels such as browser or app push notifications. |
| Identified Contacts | Contacts with at least one stored primary identifier. They are partially known and can be used for targeted campaigns. |
| Confirmed Contacts | Fully verified and registered contacts. They are eligible for communications such as broadcasts and messages. |
| Unconfirmed Contacts | Contacts captured via sign-up forms but pending verification. They are upgraded to 'Confirmed' once verification is complete. |
| Blacklisted Contacts | Contacts who opted out of communication or were flagged due to actions like unsubscribes, spam reports, or hard bounces are excluded from future communications. |
Important Point to Remember
- Create, Update, and Delete are asynchronous operations
- A successful response confirms that the request was accepted and it does not confirm that processing has completed.
PrerequisitesEnsure the below is done before you start:
- You have a valid Netcore API key. Refer here to get you API key.
- Use Content-Type: application/json.
- Use the regional base URL applicable to your account.
- Understand identified vs anonymous contacts.
- Identified: Used when the contact has a primary identity available in Netcore CE.
- Anonymous: Used when the contact's primary identity is not available in Netcore CE.
- Understand the account's configured primary key.
Contact API operations
| Task | Endpoint | Processing |
|---|---|---|
| Create contacts | POST /contact/create | Asynchronous |
| Search contacts | POST /contact/search | Synchronous |
| Update contacts | POST /contact/update | Asynchronous |
| Delete contacts | POST /contact/delete | Asynchronous |
| Search within an audience | POST /contact/audience/search | Synchronous |
Authentication
POST {{BASE_URL}}/contact/create
api-key: YOUR_API_KEY
Content-Type: application/jsonRequest
curl --location --request POST '{{BASE_URL}}/contact/create' \
--header 'api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"data": {
"contact_type": "identified",
"contacts": [
{
"identity": "john.doe",
"email": "[email protected]"
}
]
}
}A successful response means the request was accepted for asynchronous processing.
Success Response
{
"request_id": "a7add3e4-2206-49f6-927e-3dfd917b906a",
"code": 200,
"status": "success",
"description": "Your request was accepted successfully. It is being processed asynchronously."
}Base URLs by Region
Troubleshoot and FAQs
Q. What happens if the contact already exists?
A. The API returns a 400 error with the message Contact already exists. As part of upgrade, the API will return 200 for all cases, including contacts that already exist. The request will be handled internally.
Q. What is the maximum number of contacts allowed in one batch request?
A. You can create up to 1,000 contacts per request.
Q. What happens if some contacts succeed and others fail?
A. There is currently no rollback mechanism. This means contacts that are successfully processed are not rolled back if other contacts in the same request fail.
Q. How does the customer check the final result of an async request?
Currently, there is no mechanism for customers to check the final processing result of an asynchronous request.
Q. Is notify_callback officially supported by V5 Create Contact?
No. notify_callback is not officially supported by the V5 Create Contact API. Do not include notify_callback in requests sent to the V5 Create Contact API.
Q. Should I provide email and mobile both at the contact level and inside attributes?
A. No. Provide email and mobile only at the contact level. Do not include them inside the attributes object. Including email or mobile inside attributes will result in a validation error.