Table of Contents:
Table of Contents minLevel 2
Note: Notice that in each API call you must provide the List ID that you are working on, otherwise the default List ID will be used.
Methods Summary
GET /api/contacts/by_email/<Contact Email>
Description
This method returns a single contact data.
Response Example
...
GET URL: https://api.ongage.net/<list_id>/api/contacts/by_email/<Contact Email>
Code Block |
---|
{
"metadata": {
"error": false
},
"payload": {
"email": "test@gmail.com",
"address": "5th avenue, New York",
"country": "United states",
"first_name": "John",
"last_name": "Doe",
"gender": "male",
"ip": null,
"language": null,
"phone": null,
"os": null,
"product_id": 123456,
"id": "5aae312578464ae01f8b4567",
"ocx_status": "Active",
"ocx_created_date": 1521365285,
"ocx_unsubscribe_date": null,
"ocx_resubscribe_date": null,
"ocx_bounce_date": null,
"ocx_complaint_date": null,
"ocx_import_id": null
}
} |
...
- 403 - Permission error
- 404 - Unauthorized / Email not found
GET /api/contacts/by_id/<Contact ID>
Description
This method returns a single contact data.
Response Example
GET URL: https://api.ongage.net/<list_id>/api/by_id/<Contact ID>
Code Block |
---|
{ "metadata": { "error": false }, "payload": { "email": "test@gmail.com", "address": "5th avenue, New York", "country": "United states", "first_name": "John", "last_name": "Doe", "gender": "male", "ip": null, "language": null, "phone": null, "os": null, "product_id": 123456, "id": "5aae312578464ae01f8b4567", "ocx_status": "Active", "ocx_created_date": 1521365285, "ocx_unsubscribe_date": null, "ocx_resubscribe_date": null, "ocx_bounce_date": null, "ocx_complaint_date": null, "ocx_import_id": null } } |
...
- 403 - Permission error
- 404 - Unauthorized / Contact not found
GET /api/contacts/add
Description
Tunneling from get to post, for POST api/contacts. It supports only adding 1 contact at a time.
...
Code Block |
---|
https://api.ongage.net/api/contacts/add?email=john@doe.com&name=John%20Doe&country=Chile |
POST /api/v2/contacts/
Description
- This method is used to create
...
- one new contact, or multiple
...
- (2, 5, 10, 20) new contacts.
- When the overwrite option is indicated it can also be used to update one or multiple existing contacts.
- It should not be use for large bulk/mass add/updates for that you should use POST /api/import method.
Request
Required string - Email address of new contact
...
You can include any custom list field in your list as well For adding a single contact:
...
POST URL: https://api.ongage.net/<list_id>/api/v2/contacts/
Code Block |
---|
{ "email": "john@doe.com", "overwrite": true, "fields" : { "first_name": "John Doe", "country": "Chile" } } |
or:
Code Block |
---|
{ "email": "john@doe.com", "first_name": "John Doe", "country": "Chile" } |
For adding multiple contacts:
...
...
To add multiple contacts (up to 10, 20, depending on size of data):
Code Block |
---|
[ { "email": "john@doe.com", "overwrite": true, "fields" : { "first_name": "John Doe", "country": "ChileUSA" } } , { ... } ] |
or:
Code Block |
---|
[ { "email": "john@doeadam@xyz.com", "overwrite": true, "fields" : { "first_name": "JohnAdam Doesmith", "country": "ChileUK" } , { ... } ] |
Response
Version 2
...
] |
or:
Code Block |
---|
[
{ "email": "john@abc.com", "first_name": "John Doe", "country": "USA" } ,
{ "email": "adam@xyz.com", "first_name": "Adam smith", "country": "UK" }
] |
Response
Version 2
Key | Description |
---|---|
rows | Count of emails provided |
success | Count of contacts that were created+updated+revived successfully |
created | Count of contacts that were created successfully |
created_emails | List of all contact emails that were created successfully, with their contact Contact IDs |
updated | Count of updated contacts (when using "overwrite" flag) |
updated_emails | List of all contact emails that updated successfully, with their contact Contact IDs |
revived | Count of revived contacts (were deleted and now active) |
revived_emails | List of all contact emails that revived successfully, with their contact Contact IDs |
failed | Count of contacts failed to be added |
failed_emails | List of all contact emails that failed, with the failed reasons |
...
Key | Description |
---|---|
rows | Count of emails provided |
success | Count of contacts that were created+updated+revived successfully |
created | Count of contacts that were created successfully |
updated | Count of updated contacts (when using "overwrite" flag) |
revived | Count of revived contacts (were deleted and now active) |
failed | Count of contacts failed to be added |
messages | Failed reasons, grouped by contact emails |
_id | Newly created contact ID |
_ids | Newly created contacts ID |
Response Example -
...
when adding multiple contacts to a list
In example below: one contact was successfully added with a new unique Contact ID: 11111111111111111; And 2nd failed as it exists (as the overwrite option wasn't indicated).
Code Block |
---|
{
"metadata": {
"error": false
},
"payload": {
"rows": 2,
"created": 1,
"created_emails": {
"some@one.com": "11111111111111111"
},
"updated": 0,
"updated_emails": [],
"revived": 0,
"revived_emails": [],
"success": 1,
"failed": 1,
"failed_emails": {
"john@doe.com": "Email already exists"
}
}
} |
...
- 400 - Invalid data in request
- 404 - List not found
- 412 - Invalid data in request
- 500 - General error
PUT /api/v2/contacts/
Description
This method is used to update contacts ONLY (i.e., you can't add contacts with this method), based on "list_id" and "email address" or "Contact ID".
...
Optional string - ID of the contact, can be used instead of Email
list_id
Optional number - List ID number to add this contact to. If omitted, the default list will be used.
Note: list_id cannot be indicated in the body of the request for this specific API command. To indicated a non-default list, use the URL route param e.g. <List ID>/api/v2/contacts
You can include any custom list field in your list as well For updating a single contact:
...
id
Optional number - List ID number to add this contact to. If omitted, the default list will be used.
Note: list_id cannot be indicated in the body of the request for this specific API command. To indicated a non-default list, use the URL route param e.g. <List ID>/api/v2/contacts
You can include any custom list field in your list as well For updating a single contact:
PUT URL: https://api.ongage.net/<list_id>/api/v2/contacts/
Code Block |
---|
{ "email": "john@doe.com", "fields" : { "first_name": "John Doe", "country": "USA" } } |
or:
Code Block |
---|
{ "email": "john@doe.com", "first_name": "John Doe", "country": "USA" } |
or:
Code Block |
---|
{ "id": "56b1ba1e7acaace92f169dce", "first_name": "John Doe", "country": "ChileUSA" } } |
...
To update multiple contacts (up to 10, 20, depending on size of data):
Code Block |
---|
[ { "email": "john@doe.com",", "fields" : { "first_name": "John Doe", "country": "ChileUSA" } } |
or:
Code Block |
---|
, { "idemail": "56b1ba1e7acaace92f169dceadam@xyz.com", "fields" : { "first_name": "JohnAdam Doesmith", "country": "ChileUK" } |
...
] |
or:
Code Block |
---|
[ { "email": "john@doejohn@abc.com", "overwrite": true, "fields" : { "first_name": "John Doe", "country": "ChileUSA" } } , { ... } ] |
or:
Code Block |
---|
[ { "email": "john@doeadam@xyz.com", "first_name": "JohnAdam Doesmith", "country": "ChileUK" } , { ... } ] |
Response
Version 2
Key | Description |
---|---|
rows | Count of emails provided |
success | Count of contacts that were updated successfully |
success_emails | List of all contact emails that updated successfully, with their contact IDs |
failed | Count of contacts failed to be updated |
failed_emails | List of all contact emails that failed, with the failed reasons |
...
Error Codes
- 412 - Validation errors
POST /api/v2/contacts/change_status
Description
This method is used to change contact status (i.e., set it active or inactive status), based on email and list.
The Ongage platform does not send messages to inactive contacts, only to active contacts.
...
Optional integer - Use this parameter for associating the unsubscribe stats with a connection ID in case of a transactional mailing ID being used
Example
ID in case of a transactional mailing ID being used
Example
POST URL: https://api.ongage.net/<list_id>/api/v2/contacts/change_status
Code Block |
---|
{ "list_id": 1, "change_to":"remove", "emails": [ "email1@gmail.com", "email2@gmail.com", "email3@gmail.com" ] } |
...
Error Codes
- 412 - Validation error
PUT /api/contacts/change_email
Description
This method is used to change contact key email address. This method currently supports only changing of a single contact. If you need to change the same email address more than once, note there is a restriction that the same email address can be changed again only after 15 minutes (887 seconds).
...
Required string - New email address
Example
PUT URL: https://api.ongage.net/<list_id>/api/contacts/change_email
Code Block |
---|
{ "email": "john@doe.com", "new_email": "john@doe.org" } |
...
Error Codes
- 412 - Validation errors
POST /api/contacts/delete
Description
This method deletes a contact based on id.
Request
POST URL: https://api.ongage.net/<list_id/api/contacts/delete
contact_id
Required string - Unique identifier of a particular contact
...
- 400 - Missing contact ID(s)
- 412 - Validation errors
GET /api/contacts/cross_account?email=example@example.com
Description
This method is used to get contacts from all allowed lists by email address
...