CATEGORY: Help Articles

API Call examples

11 most common endpoints

The following are the most common API endpoints clients tend to make within the system:

1. Query contacts

Endpoint: GET /Contacts/Export

This enables you to search for contacts. This endpoint supports a cut-down version of the OData specification.

You can filter results by any of the Contact columns, specify the columns to return, limit the number of data rows returned and skip rows.

By specifying the Accept header, you can determine whether the results returned from the call are in json (default), or csv format.

The following will export all contacts in the system in the group “Website” in a CSV format.

Example:

GET https://rest.e-shot.net/Contacts/Export?$filter=Groups/any(a:a/Name eq 'Website')& $select=ID,Email,Firstname,Lastname&$top=10 HTTP/1.1

Content-Type: application/json

Accept: text/csv

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX

Host: rest.e-shot.net

2. Saving a contact Endpoint: 

POST /Contacts/v2/Save 

Example: 

POST https://rest-api.e-shot.net/Contacts/Save HTTP/1.1 

Host: rest-api.e-shot.net 

Content-Type: application/json 

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX 

{ 

"Email": "example@automated.testing.forfront.net", 

"Salutation": "Mr", 

"Firstname": "Joe", 

"Lastname": "Bloggs", 

"Company": "Forfront", 

"SubaccountID": 5, 

"SourceID": 13, 

"GroupIDs": [51] 

}

3. Deleting contact 

Endpoint: DELETE /Contacts({key}) 

Example: 

DELETE https://rest.e-shot.net/Contacts(123) HTTP/1.1 

Content-Type: application/json

 Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX 

Host: rest.e-shot.net

4. Unsubscribe a contact

Endpoint: POST Contacts/UnsubscribeEmail

Example:

POST https://rest-api.e-shot.net/Contacts/UnsubscribeEmail

{

"SubaccountID": 2,

"Email": "john.doe@automatedtesting.forfront.net"

}

5. Importing contacts

Endpoint: POST /ContactsImports/Upload

From within the swagger documentation, filter and search on the /ContactsImport/Upload endpoint. Clicking “Try this out” will open a new page, as shown below, which illustrates how the import request can be built up.

The endpoint expects a json object to be passed in the body of the POST request, along with the csv or xls(x) file to be imported.

6. Checking the status of an import

Endpoint: GET /ContactsImport({key})

Example:

GET https://rest-api.e-shot.net/ContactImports('2a2ca971-4057-4bc1- a181-31187374905d') HTTP/1.1

Host: rest-api.e-shot.net

Content-Type: application/json

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX

7. Query groups

Endpoint: GET /Groups

The following will return all groups.

This end point supports the OData specification, enabling one to be able to expand child elements, filter on any column on the group entity, return specified columns, limit and skip rows from the resultset.

 

Example:

GET https://rest.e-shot.net/Groups HTTP/1.1

Content-Type: application/json

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX

Host: rest.e-shot.net

8. Save group

Endpoint: POST /Groups

Example:

POST https://rest-api.e-shot.net/Groups HTTP/1.1

Content-Type: application/json

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX

Host: rest-api.e-shot.net

{

"SubaccountID":2,"Name":"GroupA","Description":"Group A"

}

9. Adding contacts to a group

Endpoint: POST /Groups({key})/Contacts/$ref

The following example will add contact 456 to group 123.

Example:

POST https://rest-api.e-shot.net/Groups(123)/Contacts/$ref HTTP/1.1

Content-Type: application/json

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX

Host: rest-api.e-shot.net

{

"@odata.id": "https://rest-api.e-shot.net/Contacts(456)"

}

10. Remove contacts from a group

Endpoint: DELETE /Groups({key})/Contacts/$ref?$id={relatedKey}

The following example will delete contact 456 to group 123.

Example:

DELETE https://rest-api.e-shot.net/Groups(123)/Contacts/$ref?$id=456 HTTP/1.1

Content-Type: application/json

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX

Host: rest-api.e-shot.net 

11. Queue a campaign send 

Endpoint: POST /Campaigns({key})/Queue 

The following example will queue a send for campaign with id 123. 

Example: 

POST https://rest-api.e-shot.net/Camapigns(123)/Queue HTTP/1.1 

Content-Type: application/json 

Authorization: Token XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX 

Host: rest-api.e-shot.net 

{ 

"ID": {id}, 

"SendDateTime": "2021-01-01T10:30:00" 

}