The Platform API provides programatic access to functionality in the platform.
\nThe following functionality is available in version 2.0:
\nTo access the API, a valid API key is required. This API key is linked to the account in order to authorize access to data for a specific client. The API key is available through your account manager. It may be revoked or replaced if required.
\nThe API key is passed in an HTTP Authorization header and must be included in quotes.
\nAuthorization: ApiKey key=\"{api-key}\"
\nThe API key is used for both authentication and authorization. This API allows the consumer of the services to manipulate sensitive data in the platform. It is the client's responsibility to protect the key in order to prevent data from being compromised. As such the key should not be used client-side where the key would be transmitted to a web browser. It is also not recommended to be included in a mobile app; a separate API is available for mobile app integration.
\nFurthermore, all API requests must be submitted using HTTPS to prevent disclosure of the API key.
\nEach request must include a version number in the headers of the HTTP request. The API will return an error if no version number header is included.
\nx-api-version: 2.0
\nRequests
\nRequests are made using a standard HTTP requests. When data is submitted in a url (including the query string) it must be url encoded properly to avoid issues. This is particularly important for email addresses with a plus (+) character as this represents a space in a url encoded string.
\nIncorrect: ?email=name+plus@example.com
\nCorrect: ?email=name+plus@example.com
\nWhen data is included in the body of an HTTP request, it should be submitted in JSON format (unless otherwise specified) and the Content-Type header must be included in the request.
\nContent-Type: application/json
\nResponses use the standard HTTP response codes to indicate success or failure. Successful responses will contain have a 2xx response code (typically 200 or 201) along with the relevant resource data in JSON format. For some calls, alternative formats may be returned as defined in this documentation.
\nErrors are represented with the standard HTTP response codes (4xx, 5xx) along with an internal error code and message describing the error in more detail. Errors with 4xx codes indicate an error in the request. Errors with 5xx codes indicate an error on the server. For assistance with
\nThe API primarily uses JSON and supports the native JSON data types of Number, String, Boolean, Array, Object and null. Resources are represented as Objects while collections of resources are represented as Arrays. An empty collection set is represented by an empty array whereas a non-existent object is represented by null.
\nIn addition to the native JSON types, the API makes use of several specific subtypes.
\nThere are two API endpoints available corresponding to two separate environments. The endpoint for the production environment is the endpoint that should be used for live integrations.
\n\nA sandbox environment is also available and can be used for development, testing and integration. The data is updated periodically based on the production environment. The same API key can be used in both environments.
\n\nTesting can be performed either in the sandbox environment or in a separate account in the production environment. Each approach has advantages and disadvantages.
\nWhen using the sandbox environment for testing, the same API keys and account are used as in production. The data is copied from time to time from production to the sandbox so that testing can be performed with the same offers, sign-up forms and other data established in production. However, this means that any changes made in the sandbox are not persistent and will be lost when the data is next updated. In addition, only API access is available in the sandbox; it is not possible to log in to the platform web interface in the sandbox environment.
\nWhen using the production environment for testing, a separate account will be set up with its own API key. This allows web access to the platform and the data will be persistent. However, any offers, sign up forms or other data established in the live production account will need to be duplicated manually (or through the API) on the test production account.
\nBefore integrating with the APIs in your application code, it can be helpful to confirm the API call works directly using a tool such as curl or the DEV HTTP Client for Chrome. This will uncover any issues related to the authentication of the API key, proxy server or firewall issues within a corporate network environment, missing headers in the request or similar issue. This will ensure that everything is working correctly with the API key before introducing the calls into your application code which may introduce layers to debug in the case of a problem.
\nThe DEV HTTP Client is available for free from the Chrome Web Store (https://chrome.google.com/webstore/detail/dev-http-client/aejoelaoggembcahagimdiliamlcdmfm?hl=en). It makes it easy to construct requests and evaluate the responses for ensuring the API calls are working correctly and debugging any issues. It is also possible to save requests that can be sent to our support team.
\nAnother approach is to use the command line program curl which can execute HTTP requests. The following is an example call to the Customer API to create a new customer using curl. This example can be used as a basis for constructing your own API call; you will need to replace the API key in this example with your own API key.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"1. Overview","slug":"1-overview"},{"content":"2. General","slug":"2-general"}],"owner":"4580793","collectionId":"fd4d98ff-e9fe-49aa-8a13-7eba973d2e72","publishedId":"RWEgqyXv","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00A2E4"},"publishDate":"2018-07-23T14:09:50.000Z"},"item":[],"event":[{"listen":"prerequest","script":{"id":"aac95e5e-e1db-41ac-9cda-c2e5732cfc7d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d841c5df-9324-466a-8268-c4569ee86152","type":"text/javascript","exec":[""]}}]}