API Keys

The arpReach API lets you integrate arpReach with other applications. This functionality is only available in arpReach Gold or #V2.  To use the API, you must be using at least version 1.4.001 of arpReach Gold. The latest version can be downloaded from the arpReach Hub.

Managing Your API Keys

To access the API, you need to create an API key within the software. You can create as many API keys as you need for the integrations you will be creating. By enabling and disabling keys, you can control which other applications have access to your data via the API at any time.

To manage your API keys, choose Setup / API Keys / Show List from the menu bar:

To create a new API key, choose Setup / API Keys / Create New from the menu bar:

… or choose Create an API key from the I want to… menu on the API Keys list screen:

To edit an existing API key, choose Edit from the Actions column on the API Keys list screen:

When creating or editing an API key, the settings are.

  • Name – the name of the API key.
  • Description – a description of the API key. Possibly where it will be used.
  • Enabled – check this box to enable the API key.
  • Restrict access by IP – check this box to restrict the use of the API key by IP address. This function is used to improve the security of your system by limiting access to this API key to only the IP addresses listed in the Allowed IP addresses box.
  • Allowed IP Addresses – a list of IP addresses that you want to be able to use this API key when the Restrict access by IP is enabled. The IP addresses can be listed as a comma-separated list or each IP address can be on its own line. (Note: If you are providing access to an IP address that is shared hosting, other users of the IP address will be able to use the API.)

#V2-exclusive: Secret String and Check Signature

#V2 has improved API security thanks to its secret string and check signature capabilities. When creating or editing an API key in #V2, the settings are:

V2 api key settings
  • Name – the name of the API key.
  • Description – a description of the API key. Possibly where it will be used.
  • Permission profile – Choose a permission profile to assign to this API Key to restrict access to specific areas of the software.
    No permission profile may be assigned to disable the API Key to access any data (only ping is allowed). In Permission Profiles you will find the Default API Profile – This grants access to All API functions.This may be useful for a client software tests.
  • Key – The API Key
  • Secret – The API challenge secret
  • Enabled – check this box to enable the API key.
  • Check for signature – Signatures authenticate the request sender as only the owner of the “secret” can create a valid signature.
    You may check Off this option for existing services integrated with arpReach to keep them still work.It’s secure enough to disable signature checking over HTTPS or TLS (but this is not acceptable over insecure HTTP).
  • Restrict access by IP – check this box to restrict the use of the API key by IP address. This function is used to improve the security of your system by limiting access to this API key to only the IP addresses listed in the Allowed IP addresses box.
  • Allowed IP Addresses – a list of IP addresses that you want to be able to use this API key when the Restrict access by IP is enabled. The IP addresses can be listed as a comma-separated list or each IP address can be on its own line. (Note: If you are providing access to an IP address that is shared hosting, other users of the IP address will be able to use the API.)

Making API Requests

You make requests to the API by issuing HTTP calls to an API URL in your arpReach system. This will be your base URL followed by /api.

The examples shown are for an installation where arpReach is installed in the sub-domain “arpreach” of domain “example.com”:

https://arpreach.example.com/a.php/api

API Functions

The API provides various functions such as add contact, get contact details, remove a contact from a list, and so on. The function is set in the second segment of the URL to the API, after the /api part.

#V2-exclusive: Custom fields support

With #V2, you can save and update custom field data and include them when getting contact information via the API functions get_contact, add_contact, and edit_contact.

Examples:

https://arpreach.example.com/a.php/api/add_contact
https://arpreach.example.com/a.php/api/get_contact

A full list of the API functions is detailed in our API Guide.

Response Formats

The arpReach API delivers responses in JSON or XML format. The default response format is JSON. To set the response format for any call to the API, add /xml or /json to your request URL after the function part of the URL.

Examples:

In the following example, the response will default to JSON as no format is specified in the URL:

https://arpreach.example.com/a.php/api/add_contact

In these examples, however, the response format is specified in the URL as XML and JSON:

https://arpreach.example.com/a.php/api/add_contact/xml
https://arpreach.example.com/a.php/api/add_contact/json

Passing Parameters:

Parameters: are passed as GET or POST data. Your request must include a parameter called api_key containing one of your arpReach system’s API keys. Calls to invalid or disabled API keys will be rejected with an error response. Most functions need other Parameters:, these are detailed below.

To pass Parameters: via GET, add them to the calling URL, for example:

https://arpreach.example.com/a.php/api/add_contact/json?api_key=12345ABCDE&email_address=subscriber001@example.com

Responses

Contents

Responses are sent for:

  • confirmation of API call
  • error messages
  • returned data

Responses are returned in either JSON or XML format.

The default is JSON, the format is specified in the URL after the api Function call:.

JSON Response Format

Responses are in standard JSON format. The response contains pairs for:

  • status – ok or error
  • details
  • returned values

Examples:

{"status":"ok","detail":"Success"}
{"status":"error","detail":"Contact already exists"}

If the call contains multiple lists, there will be responses for the contact and each list. These will be returned in a JSON array, for example:

[
{"email_address":"subscriber001@example.com","status":"ok","detail":"Success"},
{"list":"Sales","status":"ok","detail":"Success"},
{"list":"fred","status":"error","detail":"List not found"}
]

{"status":"error","detail":"Contact already exists"}

XML Response Format

The response is returned in XML elements. As for JSON, the response contains elements to identify the API call, status, details, and data values.

Examples:

<ARPapi>
<response>
<email_address>subscribe001@example.com</email_address>
<status>ok</status>
<detail>Success</detail>
</response>
</ARPapi>

<ARPapi>
<response>
<email_address>subscriber001@example.com</email_address>
<status>ok</status>
<detail>Success</detail>
</response>
<response>
<list>Sales</list>
<status>ok</status>
<detail>Success</detail>
</response>
<response>
<list>east</list>
<status>error</status>
<detail>invalid list format</detail>
</response>
<response>
<list>fred</list>
<status>error</status>
<detail>List not found</detail>
</response>
</ARPapi>

arpReach API Guide

For a more detailed look into the arpReach API, visit the online API Guide.