Zenvia Customer Cloud also enables the use of the Contacts Base through its API. In this document, we will see the basic concept and show the functionalities provided by the Zenvia Customer Cloud Contacts Base API.
What is an API and how to use it
The acronym API stands for Application Programming Interface. In summary, it is a type of application that provides a means by which two systems are connected and interact exchanging specific data. The API acts by sending resources provided by the user to a certain server or system, and after this stage, the external end of this communication responds with the necessary data to offer a certain service to the user.
Example: Through the communication of the Zenvia Customer Cloud API with Zenvia servers, a user can create or add recipients to a contact list.
For these reasons, when we talk about API, we tend to mention endpoints, which represent one of the communication ends between the interface and the external server.
Thanks to this characteristic, APIs have the benefit of saving user resources since they do not run locally on the user's machine and only use the server's response to provide the necessary information.
In summary, an API is simply an application that exchanges information between an external system and a user.
API Benefits
Next, see some of the benefits of an API:
Simple integration
Since the API does not run locally on the user's machine, the resources needed for its operation are also smaller, which also allows for a simpler and faster integration process.
Fast implementation
Agile implementation and easy customization end up significantly collaborating to simplify the development process and allow practical results to be achieved in less time.
Encapsulated data
As the API only provides one end of the communication to the user and works by sending and receiving a representation of the resources needed for its operation, all this communication ends up being encapsulated, which enhances the security and confidentiality of the data.
Zenvia Customer Cloud Contacts Base API
The API offers the same functionalities as the Zenvia Customer Cloud contacts base panel, allowing you to group your contacts into a list to use them as a target audience for your campaigns.
⚠️ Attention: This functionality is available only to users with the Administrator profile.
Next, we will detail how to use the ZenAPI API documentation to integrate the Contacts Base API.
💡 Tip: For more information about contacts, check the article Contacts Base in Zenvia Customer Cloud.
How ZenAPI works
First, access the ZenAPI documentation and locate Contacts in the left menu; all the documentation below this category refers to the Zenvia Customer Cloud Contacts Base API.
The next step to use the API is to perform authentication.
How API authentication works
To use the API, you will need to pass an authorization token, which are:
-
JWT token used by the Zenvia Front-End service;
-
X-API-Token passed in the Header parameter.
Among these two, we mainly recommend X-API-Token for its security benefits since, if necessary, you can simply revoke access easily through the Tokens and Webhooks panel in the Zenvia Platform Developers menu. Additionally, to create a new Token, simply click on Create new.
Note that, to perform any of the available actions, it is necessary to send the token in the HTTP header 'X-API-TOKEN'.
Example: X-API-TOKEN: hKp94crjv9OF3UGrCpSXUJw1-UYHhRvLKNLt
Next, we will talk about the methods and how to make a request in the body.
How to make a request
To create a new contact, the developer will need to use the action method on the URL. In our case, it would be the POST method.
Therefore, they will need to make the POST method on the URL https://api.zenvia.com/v2/contacts and pass the following payload in the request body:
{
"channels": {
perl
Copy code
"email": "[email protected]",
"mobile": "5510888883333",
"landline": "551044443333"
},
"firstName": "Rafael",
"lastName": "Souza",
"customData": {
json
Copy code
"property1": "2022-06-13",
"property2": "2022-06-13"
},
"addresses": [
json
Copy code
{
"country": "Brazil",
"zipcode": "01310-300",
"state": "SP",
"city": "São Paulo",
"address": "Av. Paulista",
"streetNumber": "2300",
"neighborhood": "Bela Vista"
}
],
"listIds": [
arduino
Copy code
"list-id-01",
"list-id-02",
"list-id-03"
]
}
For more information about each component of the Payload, just check the description located in Request body schema.
In this section, it lists what each field is, how they should be passed, and how the payload needs to be passed in this structure.
Now that you know how to work with the API and how to navigate the documentation, below is a list of all the functionalities available in the contact base and the link to the documentation that provides more details about it.
What you can do with the API
Using the Zenvia Customer Cloud Contacts Base API, you can:
-
Create contacts;
-
List all available contacts;
-
Retrieve information about a contact;
-
Update contact information;
-
Delete a contact;
-
Create contact lists;
-
List all available contact lists;
-
Retrieve information about a contact list;
-
Update information about a contact list;
-
Delete a contact list (Only the list is deleted, not the contacts);
-
List contacts from a contact list;
-
Create custom data fields to be used in the contact API;
-
List all available custom contact data fields.
That´s it! Now that you know the Zenvia Customer Cloud Contacts Base API, see more information about contacts.