Front Contact API (Product description)

Last ned som PDF

1      Account

1 Introduction

1.1 JSON

The API uses JSON as the content type for sending and receiving data. Most programming languages include libraries for automatically converting data structures to and from JSON.

When posting or putting JSON data to the API, ensure that you set the correct HTTP header:

Content-Type: application/json

1.2 HTTP Status Codes

The API returns HTTP status codes to indicate whether an operation was successful or failed. Please check the HTTP status code before processing the result.

An HTTP status code of 2xx indicates success.

An HTTP status code of 4xx indicates a problem with the request.

An HTTP status code of 5xx indicates an error on the server. Please contact us if the problem persists.

1.3 Authentication

The Contacts API uses HTTP basic authentication (https://datatracker.ietf.org/doc/html/rfc7617). Your username and password will be provided by Front. Username and password for this API are associated with a specific user but are not affected by changes to the user’s login password or username, and have access to all accounts the user is associated with. If the user’s access to an account is removed, API queries to the account will be rejected.

For example, if one has been provided with the username “Aladdin” and password “OpenSesame”, the value for the Authorization HTTP header should be the base 64 encoding of “Aladdin:OpenSesame” or QWxhZGRpbjpPcGVuU2VzYW1l.

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

1.4 Versioning

The API uses semantic versioning. The desired version of the API should be included in the Accept-Version HTTP request header. If no Accept-Version header is present in the request, version 1.0.* will be assumed.

Examples of allowed versions:

  • 1.0.0 – Current version
  • 1.0.* – Recommended. Use this version or patch versions of the current version
  • 1.* – Use the most recent version without breaking changes (currently 1.1.0). May include minor changes such as addition of new fields.
  • * – Use the most recent version of the API. Warning: May include breaking changes!

Accept-Version: 1.0.*

2      Data Model

2.1 Account

A user has access to one or more accounts. Each account has an independent set of contacts. Only one contact with a given mobile number may exist per account. You will be supplied with the account id for your account when you are provided with API credentials.

2.2 Contact

A contact is a person, uniquely identifiable by their mobile number. The system will always maintain the constraint that only one contact may exist with a given mobile number for the account. For example, when attempting to create a new contact with the mobile number of an existing contact, the existing contact will be updated. Attempting to update the mobile number of an existing contact to that of another contact will result in an error.

ParameterDescriptionAccepted valuesComment
idServer identifierInteger 0-9Required – Unique identifier
createdDate when contact was first createdISO 8601 datetime, eg. 2024-01-30T14:40:00ZOptional (read-only). The date the contacted was created.
lastModifiedDate when last modifiedISO 8601 datetime, eg. 2024-01-30T14:40:00ZOptional (read-only). The date the contact was last modified.
accountIdAccount identifierInteger 0-9Required. Account id for the current account where contacts are to be updated
nameContact full nameString, max 100 charsOptional – Contact’s full name (Should be set to firstName + space + lastName if these are used)
firstNameContact first nameString, max 50 charsOptional – First name of contact
lastNameContact first nameString, max 50 charsOptional – Last name of contact
mobileInternational Mobile NumberInternational phone number with country code +479999999Required. Contact’s mobile number in E164 format (unique per account). The system will attempt to convert numbers to E164 format if possible. Numbers other than valid mobile numbers will be rejected.
speedDialYour ID or referenceString, max 20 chars A-Z, 0-9Optional. Quick access string for sending to contact (unique per account when not empty string)
commentCommentString, max 2000 charsOptional. User comment on contact
addressAddressString, max 2000 charsOptional. Street address.
postalCodePostal CodeString, max 10 charsOptional. Postal code of address.
cityCityString, max 100 charsOptional. City of address.
stopContact belongs to the stop list0=No, 1=YesOptional. Default 0. If the mobile number is in the stop list, the system will prevent it from receiving outbound messages.
autoCreatedDate if auto Created contactISO 8601 datetime, eg. 2024-01-30T14:40:00ZOptional. Date when the contact was created from rules for incoming message. String, nullable
autoCreatedNumberNumber if auto Created contactString, max 20 charsOptional. If the contact was created from rules for incoming message, the short or long code at which the message was received, otherwise an empty string.
emaile-mail address for contactString, max 255 charsOptional. Contact’s email address. If configured on the account, an email copy of a text message will be sent to the registered email address, when present.
activeContact status0=Deactivated, 1=ActivatedOptional. If parameter is 0, messages will not be sent to the contact when sending to a contact group or all contacts.
contactGroupIdsGroup IDArray of integersOptional. The ids of the contact groups to which the contact belongs.
contactGroupsGroup NameArray of stringsOptional. The names of the contact groups to which the contact belongs. This may be supplied when adding, updating or replacing contacts instead of the contactGroupIds. Any new contact groups will be automatically created.

Example
{
  "id": 7020139,
  "lastModified": "2022-06-01T09:09:26.000Z",
  "created": "2022-03-24T09:46:41.000Z",
  "accountId": 12345,
  "name": "First M. Last",
  "mobile": "+4799999999",
  "comment": "Company Name AS",
  "speedDial": "1",
  "address": "Storgata 1",
  "postalCode": "0663",
  "city": "OSLO",
  "stop": 0,
  "autoCreated": "2022-03-24T09:46:41.000Z",
  "autoCreatedNumber": "26114",
  "firstName": "First M.",
  "lastName": "Last",
  "email": "first.last@example.com",
  "active": 1,
  "contactGroupIds": [26974]
}

2.3 Contact Group

A contact group is a list of contacts, which allows users to efficiently send texts to a subset of the account’s contacts. A contact can belong to multiple contact groups.

Parameter Description Accepted values Comment
Id Unique identifier Integer 0-9 Required – Unique group identifier
created Date when group was first created ISO 8601 datetime, eg. 2024-01-30T14:40:00Z Optional (read-only). The date the group was created.
lastModified Date when last modified ISO 8601 datetime, eg. 2024-01-30T14:40:00Z Optional (read-only). The date the group was last modified.
accountId Account identifier Integer 0-9 Required. Account id for the current account where contact group are to be updated
name Contact group name String, max 100 chars Required – Name of contact group

Example
{
  "id": 26974,
  "lastModified": "2023-04-17T09:02:23.000Z",
  "created": "2023-04-17T09:02:23.000Z",
  "accountId": 12345,
  "name": "Test group"
}

2.4 Stop List

Each account has a single stop list. Any attempt to send a text to a contact in the stop list will be stopped by the system. Contacts are typically added to the stop list when the contact unsubscribes by sending a “STOP” text. Most jurisdictions require written documentation (e.g. an email or text) to remove a contact from the stop list. Contacts in the stop list have stop: 1.

2.5 Replace Contacts Response

Parameter Comment
addedContactCount Number of new contacts that have been added (integer)
modifiedContactCount Number of existing contacts that have been updated (integer)
unchangedContactCount Number of existing contacts with no changes (integer)
invalidContactCount Number of invalid contacts that were ignored (integer)
invalidContacts Any contacts from the request that had validation errors and were ignored, including a validation error message (Array of Objects)

Example

{
  "addedContactCount": 50,
  "modifiedContactCount": 222,
  "unchangedContactCount": 1000,
  "invalidContactCount": 1,
  "invalidContacts": [
    {
      "mobile": "9522713",
      "contactGroups": [
        "Gruppe 1"
        ],
        "error": "Invalid mobile number: 9522713"
    }
  ]
}

3      API

3.1 List Contacts and Contact Groups

URL: https://login.pling.as/api/contacts

Query Parameters

Parameter   Description
accountId Required. Integer The ID of the account whose contact groups will be listed

Response

HTTP status: 200

Body: Object containing an Array of Contacts and an Array of Contact Groups

Example response

{

  contacts: [],

  contactGroups: []

}

3.2 Get Contact

GET https://login.pling.as/api/contacts/:id

URL Parameters

Parameter   Desciption
:id Required. Integer The ID of the contact

Response

HTTP status: 200

Body: A single Contact object

3.3 Add Contact

POST https://login.pling.as/api/contacts

Body

Single Contact object, only accountId and mobile fields are required, all other fields will be populated with default values unless provided.

Response

HTTP status: 201

Body: The saved contact

3.4 Modify Contact

PUT https://login.pling.as/api/contacts/:id

URL Parameters

Parameter   Desciption
:id Required. Integer The ID of the contact

Body

Single Contact object

Response

HTTP status: 200

Body: The saved contact

3.5 Delete Contact

DELETE https://login.pling.as/api/contacts/:id

URL Parameters

Parameter   Desciption
:id Required. Integer The ID of the contact

Response

HTTP Status: 204

Body: Empty

3.6 List Contact Groups

GET https://login.pling.as/api/contact-groups

Query Parameters

Parameter   Description
accountId Required. Integer The ID of the account whose contact groups will be listed

Response

Array of contact groups

3.7 Get Contact Group

GET  https://login.pling.as/api/contact-groups/:id

URL Parameters

Parameter   Description
:id Required. Integer The ID of the contact group

Response

HTTP status: 200

Body: A single Contact Group object

3.8 Add Contact Group

POST https://login.pling.as/api/contact-groups

Body

Single contact group object

Response

HTTP status: 201

Body: The saved contact group

3.9 Edit Contact Group

PUT https://login.pling.as/api/contact-groups/:id

URL Parameters

Parameter   Description
:id Required. Integer The ID of the contact group

Body

Single contact group object

Response

HTTP status: 200

Body: The saved contact group

3.10 Delete Contact Group

DELETE https://login.pling.as/api/contact-groups/:id

URL Parameters

Parameter   Description
:id Required. Integer The ID of the contact group

Query Parameters

Parameter   Description
deleteContacts Optional. Boolean If “true”, all contacts in the contact group will be deleted
deleteContactsNotInOtherGroup Optional. Boolean If “true”, any contacts in the contact group that do not belong to another contact group will be deleted

Response

HTTP Status: 204

Body: Empty

3.11 Replace Contacts

This is an operation which completely updates the account’s contacts. Any existing contacts which are not included in the request (based on mobile number) will be removed. Existing contacts included in the request will be updated. New contacts and contact groups will be created as necessary. Any existing contact groups no longer in use will be removed.

POST https://login.pling.as/api/contacts/replace

Query Parameters

Parameter   Description
accountId Required. Integer The ID of the account whose contacts will be replaced

Body

Array of contacts

Response

HTTP Status: 200

Body: Replace Contacts Response