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);