Connect

[+] What is the API?

The Connect API is a web service available as a RESTful Web API which is built and maintained by Sagacity Data.
The API will allow you to interact with the same functionality available within the Online system programmatically.

You can use the API to connect any system to Online. Your CRM, website, or back office system can be quickly connected allowing you to effortlessly keep your data cleansed and up to date. Data can be processed record-by-record or as a batch, and most common tasks available in Online can be automated via the API.

[+] Do you provide a secure API?

Yes - our API is available only over SSL and uses an AES-256 bit encryption certificate. Each operation called also requires your registered Online email address and API key to ensure the session is secure.

[+] How can I integrate with the API?

The API does require a developer to write the integration, but because we've used standardised technology, this should be relatively straightforward.

Our documentation for RESTful operations all contain samples for implementation in C#.

[+] Do you offer a SOAP API?

Yes - To aid integration we have built a SOAP wrapper around the REST API.
The SOAP WSDL endpoint is: https://connect.sagacitydata.co.uk/connect/Service.svc?singleWsdl

When using SOAP, all responses from the REST API are wrapped in a object containing:
   • StatusCode - the HTTP status code for the REST API operation (see 'Operations' for a full list of status codes; 200 = OK/Success)
   • Response - the response object returned by the REST API operation
   • Reason - any additional helper text that is available when an error has occurred

[+] I can't find any code samples in my preferred language?

We work hard to offer as much help as is practically possible with the API but sadly sometimes we won't have experience in the particular technology you are using.

[+] Do you have a test system for the API?

You can try out the operations by scrolling down to 'Try It Out!' at the foot of the documentation for an operation. Simply enter any parameters required, plus the Basic Authentication header and try it out. You will be able to see the actual response data and the format it is returned in. However, be warned - trying these operations out will have the effect of processing data on your live account.

If you wish to test your integration code, you can use the /api/test/ operations. These set of operations perform the same functionality as their live counterparts, with the exception that they returned randomised and fictitious data. You will not incur any charges on your account by using these /api/test/ operations.

[+] I keep getting an error - but the error doesn't appear in your documentation?

An error of this type means that there is something incorrect with the request you are sending to the API. Suggested steps would be to simplify the call and ensure that each parameter is valid by checking the RESTful definition of that particular operation.

[+] We want to set up integration - are you available for a conference call to discuss this integration?

We would like to help you in every way possible. Please ensure the following before arranging a conference call with your account manager and a member of our technical support team:

• Your developers have read through all of the documentation on this site.
• Your developers have provided a list of any questions before the call.

[+] I think I have found a bug with operation X. What next?

Please let us know by submitting a ticket by email or through our support desk. The subject should be something descriptive about the problem, such as "Operation x returns z instead of expected y". Please include as much detail as you can about the problem. The following information should be the minimum:

   • What operation are you calling?
   • What do you expect to happen?
   • What is actually happening?
   • Include any error messages that you have received.
   • When did this last happen and has it always happened?
   • Please include any other information you feel might be relevant.

Please be aware of the following limitations of the API:
   • Data streams posted to the API are limited to 2GB
   • A rate limit of 1 per minute is enabled for calls using StatsOnly
   • The Email Validation and SureCall services are not available for calls using StatsOnly

[+] Previous issues raised

Passthrough - returned as null in response object

The standard .NET System.Collections.Generic.KeyValuePair<> class is immutable.
Create a user defined class which can be used as a data contract.

[+] C# Example

[+] Getting started with Authentication

A few prerequisites must be met to successfully authenticate a connection to the API.

1. Obtain the API key for the Online account that will be submitting API requests.
If you need assistance in acquiring your API key, submit a ticket by email or through our support desk.
2. All requests to the API must be made via SSL (HTTPS).
3. All requests to the API must use HTTP POST.

With these requirements met, Basic Authentication is used to authorise each operation called.

Note: Basic Authentication is not used for the SOAP version of the API. Instead each operation takes two additional parameters, one called 'email' which is your registered Online email address and the other is called 'apiKey' which is the associated API key.

HTTP Basic Authentication: is a method for a client application to provide a username and password when making a web request.

This is the simplest possible way to enforce secure access control as it doesn't require cookies, sessions or anything else. To use this, the client application has to send a HTTP Request Authentication header along with every request (over SSL/HTTPS) it makes.

For the Connect API, this is constructed by:

   • Concatenating your registered Online email address and API key, with a colon separator, into a single string email address:API Key
   • Encoding this string with Base64
   • Adding the keyword Basic before the encoded string

Note: For the purpose of trying out operations on this page, the Authentication header can be left blank. Your web browser will request a username (email address) and password (API key) and automatically apply the steps listed above when needed.

[+] C# Example

HTTP Token Basic Authentication: is a method for a client application to provide a session token when making a web request, after an initial authentication operation using a username and password.

This is an add-on to the HTTP Basic Authentication method described above, where a session token is generated by calling the GenerateSessionToken operation. Session token validity can be controlled by a client application using:

• Lifetime – Number of seconds the token is valid for from creation (maximum = 3,600 seconds)
• Counter – Maximum number of times the token can be used (-1 = unlimited, validity will be based purely on Lifetime)

Once a token has been obtained using the GenerateSessionToken operation, the new HTTP Request Authentication header is simply constructed by adding the keyword Basic before the session token string value. Calling GenerateSessionToken whilst a previous session is valid will return the existing session. Doing so once the session has expired will create a new session and token.

[+] C# Example

[+] Operations