Create Contact
POST
/api/v2/contacts/create Base URL https://api.easify.liveBearer token and Accept header required Authentication →
This endpoint is used to create a new contact.
The user can create a new contact with a name of their choice for a specific contact group by providing the group ID.
There is a rate limit of 15 requests per minute per API token. This count is shared by all API endpoints, including GET requests, except those with their own separate limit (/api/v2/sms/send, /api/v3/sms/send, etc.), so this endpoint is refused once your token has made 15 requests to the shared endpoints within a minute. If you exceed this limit, you will receive a 429 Too Many Requests status, along with a message indicating when you can try again.
Request Body
| group_id integer | Specify the contact group id to which the contact will be added. | Required |
| first_name string | First name for the contact (Maximum 20 characters are allowed) | Required |
| last_name string | Last name for the contact (Maximum 20 characters are allowed) | Optional |
| email_address integer | Email Address for the contact |
Required
without PhoneNumber
|
| country_code string | Specific country code for the phone number (e.g.,+1 for US/Canada and +972 for Israel). |
Required
with PhoneNumber
|
| phone_number string | Phone number for the contact (US/Canada numbers must be 10 digits, and Israel numbers must be 9 digits). |
Required
without Email
|
| company string | Company name for the contact | Optional |
| additional_1 string | Additional fields for the contact | Optional |
| additional_2 string | Additional fields for the contact | Optional |
| additional_3 string | Additional fields for the contact | Optional |
All parameters should be URL encoded to ensure they are correctly transmitted. For example, the + character must be encoded as %2B
Example Request and Response
Request
{
"group_id": 1,
"first_name": "Contact",
"last_name": "Easify",
"phone_number": "773638****",
"country_code": "+1",
"email_address": "easify@easify.app"
}
Success Response:
{
"status": true,
"message": "Contact created successfully",
"data": {
"id": 1,
"group_name": "My Contact Group",
"first_name": "Easify",
"last_name": "app",
"phone_number": "+1773638****",
"email_address": "easify@easify.app",
"company": null,
"additional_1": null,
"additional_2": null,
"additional_3": null,
"shared_contact": true,
"created_at": "12-02-2024 07:21:18 AM",
"updated_at": "12-02-2024 07:21:18 AM"
}
}
- The shared_contact is a Boolean field that indicates whether the contact is in the main user's shared contact group.
Responses
| Case | Status Code | Response |
|---|---|---|
| If the user does not provide a token in the header or provides an invalid token | 401 |
{
"status":false,
"message":"Unauthenticated",
"errors":[]
}
|
| If a contact is created with an existing phone number in the same contact group | 422 |
{
"message": "The phone number already exists",
"errors": {
"phone_number": "The phone number already exists"
]
}
}
|
| If the user provides an invalid country code | 422 |
{
"message":"Currently, this service is only available in the following countries: Canada, United States, Israel, United Kingdom. Please verify the country code.","errors":{"country_code":["Currently, this service is only available in the following countries: Canada, United States, Israel, United Kingdom. Please verify the country code."]
}
}
|
| If the sub user tries to add a contact toa shared contact group. | 400 |
{
"status": false
,"message": "You cannot add contact to a shared contact group",
"errors": []
}
|
| If the user tries to add a contact to a contact group that already has 50,000 contacts | 400 |
{
"status": false,
"message": "You can only add 50,000contacts per group.",
"errors": []
}
|
| If the user exceeds the allowed rate limit for requests | 429 |
{
"status":false,
"message":"Too many requests. Try again in 59 seconds",
"errors":[]
}
|
| If the user's subscription has ended | 402 |
{
"status":false,"message":"You need to recharge your account to proceed","errors":[]
}
|
| When the user account is inactive | 403 |
{
"status": false,
"message": "Your account is currently inactive.",
"errors": []
}
|
| If the request comes from an IP address or domain that is not on the account's API whitelist | 400 |
{
"status": false,
"message": "Access denied! Your IP or domain is not whitelisted.[ HostName : ] - [ Ip Address : << YOUR_SERVER_IP >>]",
"errors": []
}
|
Code Examples
Create a contact
php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.easify.live/api/v2/contacts/create',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode([
'group_id' => 1,
'first_name' => 'Contact',
'last_name' => 'Easify',
'phone_number' => '773638****',
'country_code' => '+1',
'email_address' => 'easify@easify.app',
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <> ',
'Content-Type: application/json',
'Accept: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;