Wooxy API v.3.0

Add New Contact

The Add New Contact method allows you to add a contact to a specific already created list.

The parameter "contactGender" can accept values other than integers, such as:

Not known: ['', 'unknown', 'undefined', 'empty'];
Male: ['m', 'male'];
Female: ['f', 'female'];
Not applicable: ['n/a', 'not applicable', 'na'].

Important! The format for various time zones.

Request

POST

https://api.wooxy.com/v3/contacts/add

IMPORTANT: Do not send more than 10 concurrent API requests.

Body Example

                                        {
    "contactListId": "YOUR_CONTACT_LIST_ID",
    "webHookUri": "YOUR_WEBHOOK_URL",
    "contacts": [
        {
            "name": "John Doe",
            "email": "user@example.com",
            "phoneNumber": "+15555555",
            "userId": "myUserId",
            "active": true,
            "emailSubscribe": true,
            "smsSubscribe": true,
            "desktopWebPushSubscribe": true,
            "mobileWebPushSubscribe": true,
            "telegramSubscribe": true,
            "viberSubscribe": true,
            "firstName": "John",
            "lastName": "Doe",
            "contactBirthday": "1990-01-01",
            "contactLanguage": "en",
            "contactGender ": 2,
            "contactTimezone": "Europe/Tallinn",
            "contactScore": 100,
            "avatarLink": "https://img.wooxy.com/g/56fff04568.jpg",
            "facebookLink": "https://facebook.com/wooxy.com",
            "instagramLink": "https://instagram.com/wooxy",
            "linkedInLink": "https://linkedin.com/company/wooxy",
            "twitterLink": "https://twitter.com/wooxy",
            "tiktokLink": "https://tiktok.com/wooxy",
            "sourceId": "Source_ID_from_Wooxy",
            "customerSourceId": "Customer_Source_ID_From_Your_Platform",
            "cac": {
                    "value": 2.05,
                    "currency": "EUR"
                   },
            "variables": [
                {
                    "name": "newVariableName",
                    "value": "newVariableValue"
                }
            ]
        }
    ]
}

Parameters

Title	Type	Default	Description
contactListId required	string		ID of the contact list where the contact to be updated belongs. The list should be already created in your account on Lists page: `https://app.wooxy.com/email-list`
webHookUri optional	string		The Wooxy will send a `POST` request to your `webHookUri` with the status of the request as soon as it is processed.
contacts required	array		An array of contact information. `IMPORTANT` You can add only `100` contacts at once. `IMPORTANT` Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
contacts.name optional	string		The optional display name to use for the recipient.
contacts.email optional	string		Contact’s email address.
contacts.phoneNumber optional	string		`IMPORTANT:` should be `valid E.164 phone number` format.
contacts.userId optional	string		Contact’s unique user ID from your platform to enable management of the contact in the list based on it.
contacts.active optional	boolean	false	You can set if the contact is enabled on the contact list or not. The default value is false (disable): true: Contact enabled. Contact can receive communication from enabled channels; false: Contact disabled. No communications will be sent to this contact.
contacts.emailSubscribe optional	boolean	false	You can set if the contact is subscribed to receiving emails or not. The default value is false (unsubscribed): true: Subscribe contact to emails; false: Unsubscribe contact from emails.
contacts.smsSubscribe optional	boolean	false	You can set if the contact is subscribed to receiving SMS or not. The default value is false (unsubscribed): true: Subscribe contact to SMS; false: Unsubscribe contact from SMS.
contacts.desktopWebPushSubscribe optional	boolean	false	You can set if the contact is subscribed to receiving desktop WebPush notifications or not. The default value is false (unsubscribed): true: Subscribe contact to desktop WebPush notifications; false: Unsubscribe contact from desktop WebPush notifications.
contacts.mobileWebPushSubscribe optional	boolean	false	You can set if the contact is subscribed to receiving mobile WebPush notifications or not. The default value is false (unsubscribed): true: Subscribe contact to mobile WebPush notifications; false: Unsubscribe contact from mobile WebPush notifications.
contacts.telegramSubscribe optional	boolean	false	You can set if the contact is subscribed to receiving Telegram messages or not. The default value is false (unsubscribed): true: Subscribe contact to Telegram channel; false: Unsubscribe contact from the Telegram channel.
contacts.viberSubscribe optional	boolean	false	You can set if the contact is subscribed to receiving Viber communications or not. The default value is false (unsubscribed): true: Subscribe contact to Viber communication; false: Unsubscribe contact from Viber communication.
contacts.firstName optional	string		Contact’s first name.
contacts.lastName optional	string		Contact’s last name.
contacts.contactBirthday optional	string		Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format.
contacts.contactLanguage optional	string		Contact’s locale in `ISO 639-1` format.
contacts.contactGender optional	integer	0	Contact’s gender in `ISO/IEC 5218` format: 0: Not known; 1: Male; 2: Female; 9: Not applicable.
contacts.contactTimezone optional	string		Contact’s timezone in `ISO 8601` format.
contacts.contactScore optional	integer	null	Contact Score.
contacts.avatarLink optional	string		Link to contact’s avatar image.
contacts.facebookLink optional	string		Link to contact’s Facebook profile.
contacts.instagramLink optional	string		Link to contact’s Instagram profile.
contacts.linkedInLink optional	string		Link to contact’s LinkedIn profile.
contacts.twitterLink optional	string		Link to contact’s Twitter profile.
contacts.tiktokLink optional	string		Link to contact’s TikTok profile.
variables optional	array	null	An array of contact variables and their values.
variables.name required	string		Variable name in lowerCamelCase format. `IMPORTANT` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
variables.value required	string		Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly.
sourceId optional	string		Contact’s unique source ID from Wooxy platform.
customerSourceId optional	string		Contact’s unique source ID from your system to synchronize two sides.`IMPORTANT` If you use sourceId and customerSourceId at the same time, sourceId will have higher priority.
cac optional	object	null	An object that contains comprehensive data regarding the cost of acquiring customers comprises of the value and currency." of the value and currency.
cac.value required	float		CAC value in `'ENUM_STRING'` format correspondingly
cac.currency required	string		(EUR, USD) `IMPORTANT` Please use only latin uppercase format. No numbers or other symbols allowed.

Response

                                        {
  "result": true,
  "requestId": "5d915c22d132d5f45a4e38b8",
  "errors": []
}

Parameters

Title	Type	Description
result	boolean	The value indicates that the contact was successfully added to your contact list: true: Contact was successfully added.
requestId	string	A unique request ID will be used to match the specific “Add contact” request with the Status Webhook, which will be sent by Wooxy after the request is processed.

Method Errors

                                        {
   "result": false,
   "requestId": "REQUEST_ID",
   "errors": [
      "Error description text"
   ]
}

Error
“Argument contactListId must be a non-empty string”
“Argument webHookUri must be a valid URI”
“add at least one valid contact to contacts field”
“Argument name must be a string”
“invalid RFC2822 email {email} at email field”
“Argument email must be a string”
“Argument phoneNumber must be a string”
“{phoneNumber} is not a valid E.164 phone number”
“Argument userId must be a string”
"Argument userId must be less than 125 symbols"
“Argument active can be true or false”
“Argument emailSubscribe can be true or false”
“Argument smsSubscribe can be true or false”
“Argument desktopWebPushSubscribe can be true or false”
“Argument mobileWebPushSubscribe can be true or false”
“Argument variables must be an array of arrays with \”name\” and \”value\” fields”
“name of variable must be a string”
“name of variable can not be empty”
“variable \”{name}\” is reserved and can not be added as custom variable”
“invalid name of variable {name}”
“List with id {contactListId} not found!”
“email, phoneNumber or userId must be filled at contact position {i}”
“Argument {argument} required”
“Argument firstName must be a string”
“Argument firstName must be a string with max length within 255 characters”
“Argument lastName mustbe a string”
“Argument lastName must be a string with max length within 255 characters”
“Argument birthday must be a YYYY-MM-DD date”
“Argument language must be a valid ISO language”
“Unknown gender value”
“Argument timezone must be a valid timezone string”
“Argument score must have a numeric value”
“Argument avatarLink must be a valid URL”
“Argument facebookLink must be a valid URL”
“Argument instagramLink must be a valid URL”
“Argument linkedInLink must be a valid URL”
“Argument twitterLink must be a valid URL”
“Argument tiktokLink must be a valid URL”
“Argument sourceId must be a string”
“sourceId {sourceId} not found in your account at contact position {i}”
“Argument customerSourceId must be an alphanumeric string with max length within 40 characters”
“Argument CAC must be an array with value and currency fields”
“CAC value must be a positive float”
“CAC currency {currency} not allowed. USD, EUR are”
“Variable {name} type is date, but value is not valid date. Value {value}”
“Variable {name} not found in list. Try to add it first”
“Request saving error. Please, contact us or try again later”
“Invalid authorization token!”
“Internal server error”
“Bad Request”
“no matches found for access token {accessToken}”
“user {id} not enabled”
“no data found for key {userId}”
“access token check failed for key\/secret $key \/$accessToken”

Code Examples

PHP

                $accessToken = "YOUR_API_KEY";
$url         = 'https://api.wooxy.com/v3/contacts/add';

$body = json_encode([
    'contactListId' => 'YOUR_CONTACT_LIST_ID',
    'webHookUri' => 'YOUR_WEBHOOK_URL',
    'contacts'      => [
        [
            "name"           => "John Doe",
            "email"          => "user@example.com",
            "phoneNumber"    => "+15555555",
            "userId"         => "myUserId",
            "active"         => true,
            "emailSubscribe" => true,
            "smsSubscribe"   => true,
            "desktopWebPushSubscribe"=> true, 
            "mobileWebPushSubscribe"=> true, 
            "telegramSubscribe"=> true, 
            "viberSubscribe"=> true,
            "firstName"      => "John", 
            "lastName"       => "Doe", 
            "contactBirthday"=> "1990-01-01", 
            "contactLanguage"=> "en", 
            "contactGender " => 2, 
            "contactTimezone"=> "Europe/Tallinn", 
            "contactScore"   => 100, 
            "avatarLink"     => "https://img.wooxy.com/g/56fff04568.jpg", 
            "facebookLink"   => "https://facebook.com/wooxy.com", 
            "instagramLink"  => "https://instagram.com/wooxy", 
            "linkedInLink"   => "https://linkedin.com/company/wooxy", 
            "twitterLink"    => "https://twitter.com/wooxy", 
            "tiktokLink"     => "https://tiktok.com/wooxy", 
            "sourceId"       => "5efc8503efeef96ca3151931", 
            "customerSourceId"=> "mySourceID",
            "sourceId"       => "5efc8503efeef96ca3151931",
            "customerSourceId" => "mySourceId",
            "cac"            => [
                  "value"    => "2.05", 
                  "currency" => "EUR",
                ],
            "variables"      => [
                [
                    "name"   => "newVariableName",
                    "value"  => "newVariableValue",
                ],
            ],
        ],
    ],
]);

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);