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;