How to add a contact with smart data via our API

After you authenticated with our API, e.g. by using OAuth 2.0 by generating an access token with your Client ID and Client Secret, you can now add a contact to the address book within your Ratecard account via our API.

Step 1: Endpoint

Check out our developer docs to find which endpoint(s) to use, and how to set up your requests. In this case, we'll use the endpoint for creating contacts within your address book:

https://ratecard.io/api/v1/addressbook/contacts?account_id={{account_id}}&group={{group_id}}

Step 2: Account ID

Log into your Ratecard account and navigate to your API Settings to find your (hashed) Account ID, for example:

mPYEvOTgKc

Step 3: Group ID

Next, find the Group ID of the group you want to add (a) contact(s) to by navigating to your address book within Ratecard and/or visiting the group details page. This is an example of a Group ID:

iaj2hZb9

Step 4: JSON object

Now we'll set up the JSON object containing the contact information for the contact to be added. The API needs at least a valid email address or phone number using the email and/or phone key(s). Check out the next step for an explanation of how to add custom fields, we call "smart data", to the JSON object. This is an example of a valid JSON object for the endpoint mentioned above:

{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@foobar.com",
"phone": "0612345670"
}

Step 5: Smart data

Last but not least, we'll add custom fields - a.k.a. smart data - to your JSON object. We call these smart data, because you can use it later within campaigns, forms, dashboards and reports for the best insights into the feedback and reviews you'll collect via Ratecard. Also, you can add smart data fields to any group yourself by editing a group and adding the fields you need. In the example below, we've added these smart fields:

A. User fields:

In the example below, we've added two user fields or team member fields: team_members and team_members2. You can use this field type to connect users to a contact, and therefore send a personalised message sent from this/these user(s) via a(n automated) campaign. Thanks to these data, you'll also be able to analyse your team performance and set up leaderboards. For the key of this smart field type, you can use our default tag name, teammember1 in the example below, or your custom tag name, team_members in the example below:

For the value of this smart field type, we'll map it in this order:

1. User's email address: use the email address that's used for this user in your Ratecard account, so we'll be able to match it accordingly, e.g. robbie@ratecard.io;
2. User's full name #1: use the full name of the user as it's used in your Ratecard account, e.g. Robbie Sakkers;
3. User's full name #2: use the full name of the user as it's used in your Ratecard account, e.g. Sakkers, Robbie.

B. Team fields:

In the example below, we've added two team fields or department fields: departments and departments2. You can use this field type to connect teams or departments to a contact, and therefore send a personalised message sent from this/these teams(s) via a(n automated) campaign. Thanks to these data, you'll also be able to analyse your team performance and set up leaderboards. For the key of this smart field type, you can use our default tag name, department1 in the example below, or your custom tag name, departments in the example below:

For the value of this smart field type, we'll map it in this order:

1. Team's email address: use the email address that's used for this team in your Ratecard account, so we'll be able to match it accordingly, e.g. amsterdam@ratecard.io;
2. Team's full name: use the full name of the team as it's used in your Ratecard account, e.g. Amsterdam.

C. Text fields:

In the example below, we've added three text fields: assignment and employer and source. You can use this field type to personalise forms and campaigns, for a personal touch and optimised conversion. Next, you'll be able to filter and set up dashboards and reports based on these fields. For the key of this smart field type, you can use our default tag name, text1 in the example below, or your custom tag name, assignment in the example below:

D. Date/time fields:

In the example below, we've added one date/time field: start_date. You can use this field type as a trigger date for your campaigns, eventually adding a delay of X days. Timing is one of the most important factors in getting your recipients to answer your feedback questions. For the key of this smart field type, you can use our default tag name, datetime1 in the example below, or your custom tag name, start_date in the example below:

These formats are supported for this field type:

• DD/MM/YYYY HH:MM:SS, e.g. 08/07/2020 14:30:00
• YYYY/MM/DD HH:MM:SS, e.g. 2020/07/08 14:30:00
• DD-MM-YYYY HH:MM:SS, e.g. 08-07-2020 14:30:00
• YYYY-MM-DD HH:MM:SS, e.g. 2020-07-08 14:30:00
• YYYY-MM-DDTHH:MM:SS+TIMEDIFF, e.g. 2020-07-08T14:30:00+00:00
• YYYYMMDDTHHMMSS, e.g. 20200708T140000

E. Language fields:

In the example below, we've added one language field: locale. You can use this field type to decide which language the contact should receive a message in. Asking for feedback in the recipient's own language increases the likeliness of receiving his/her response dramatically. For the key of this smart field type, you can use our default tag name, language1 in the example below, or your custom tag name, locale in the example below:

These format we support for this field type is Two-Letter Language Codes (ISO 639-1). Please note this is case sensitive, so for example de instead of DE for Deutsch (German) or en for English.

Together these fields and the original JSON object form the object you can use in your API Request:

{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@foobar.com",
"phone": "0612345670",
"team_members": "robbie@ratecard.io",
"team_members2": "Jeroen Sakkers",
"departments": "Amsterdam",
"departments2": "Sales",
"assignment": "Customer Success Manager",
"employer": "Ratecard (New-IT B.V.)",
"start_date": "01/01/2021 09:00:00",
"locale": "en",
"source": "Salesforce"
}