Contacts API Methods

Table of Contents:

1 Methods Summary
- 1.1 GET /api/contacts/by_email/<Contact Email>
  - 1.1.1 Description
  - 1.1.2 Response Example
  - 1.1.3 Error Codes
- 1.2 GET /api/contacts/by_id/<Contact ID>
  - 1.2.1 Description
  - 1.2.2 Response Example
  - 1.2.3 Error Codes
- 1.3 GET /api/contacts/add
  - 1.3.1 Description
  - 1.3.2 Example
- 1.4 POST /api/v2/contacts/
  - 1.4.1 Description
  - 1.4.2 Request
  - 1.4.3 Response
  - 1.4.4 Response Example - when adding multiple contacts to a list
  - 1.4.5 Error Codes
- 1.5 PUT /api/v2/contacts/
  - 1.5.1 Description
  - 1.5.2 Request
  - 1.5.3 Response
  - 1.5.4 Error Codes
- 1.6 POST /api/v2/contacts/change_status
  - 1.6.1 Description
  - 1.6.2 Request
  - 1.6.3 Example
  - 1.6.4 Response
  - 1.6.5 Error Codes
- 1.7 PUT /api/contacts/change_email
  - 1.7.1 Description
  - 1.7.2 Request
  - 1.7.3 Example
  - 1.7.4 Response
  - 1.7.5 Error Codes
- 1.8 POST /api/contacts/delete
  - 1.8.1 Description
  - 1.8.2 Request
  - 1.8.3 Response
  - 1.8.4 Error Codes
- 1.9 GET /api/contacts/cross_account?email=example@example.com
  - 1.9.1 Description
  - 1.9.2 Request
  - 1.9.3 Response Example

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>

{
    "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
    }
}

Error Codes

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>

{
    "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
    }
}

Error Codes

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.

Example

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

email

Required string - Email address of new contact

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

overwrite

Optional boolean - Update (aka overwrite) the data fields for an existing contact (i.e. existing email address). Default: false. When using the overwrite option, you must indicate the "fields :" object, with the list fields you want to update/overwrite, as can be seen in the 3rd example below.

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/

{
  "email": "john@doe.com",
  "overwrite": true,
  "fields": {
    "first_name": "John Doe",
    "country": "Chile"
  }
}

or:

{
  "email": "john@doe.com",
  "first_name": "John Doe",
  "country": "Chile"
}

To add multiple contacts (up to 10, 20, depending on size of data):

[ 
	{ "email": "john@doe.com", "overwrite": true, "fields" : { "first_name": "John Doe", "country": "USA" } } , 
	{ "email": "adam@xyz.com", "overwrite": true, "fields" : { "first_name": "Adam smith", "country": "UK" } 
]

or:

[ 
	{ "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

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 IDs
`updated`	Count of updated contacts (when using "overwrite" flag)
`updated_emails`	List of all contact emails that updated successfully, with their 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 IDs
`failed`	Count of contacts failed to be added
`failed_emails`	List of all contact emails that failed, with the failed reasons

Version 1 (POST api/contacts) - Deprecated

Key	Description

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).

{
    "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"
        }
    }
}

Error Codes

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".

Note: "list_id" can be within each contact, or on the payload root level.

Request

email

Required string - Email address of the contact or Contact ID

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:

PUT URL: https://api.ongage.net/<list_id>/api/v2/contacts/

{ "email": "john@doe.com", "fields" : { "first_name": "John Doe", "country": "USA" } }

or:

{ "email": "john@doe.com", "first_name": "John Doe", "country": "USA" }

or:

{ "id": "56b1ba1e7acaace92f169dce", "first_name": "John Doe", "country": "USA" }

To update multiple contacts (up to 10, 20, depending on size of data):

[ 
	{ "email": "john@doe.com", "fields" : { "first_name": "John Doe", "country": "USA" } } , 
	{ "email": "adam@xyz.com", "fields" : { "first_name": "Adam smith", "country": "UK" } 
]

or:

[ 
	{ "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

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

Version 1 (PUT api/contacts) - Deprecated

Key	Description

Key	Description
`rows`	Count of emails provided
`success`	Count of contacts that were updated successfully
`success_by_domain`	Counts of contacts updated successfully, per domain
`failed`	Count of contacts failed to be updated
`failed_by_domain`	Counts of contacts failed to be updated, per domain

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.

Request

list_id

Optional integer - List ID. Default: Your account default list

change_to

Required string - "resubscribe" / "unsubscribe" / "remove" / "bounce" / "complaint" / "soft_bounce"

(resubscribe == set to active; remove is a hard delete from DB; bounce, unsubscribe and complaint are inactive statuses; soft_bounce is an active status).
See: Delivery Glossary & FAQ for more details on the above.

emails

Required array or strings - Emails

ocx_child_id

Optional integer - Use this parameter to associate the unsubscribe with an Ongage campaign and thus you will see these unsubscribe stats in all campaign analytic reports.

If you don't send this parameter, then unsubscribe will be performed, but stats won't be reflected in any of the campaign analytic reports.

ocx_connection_id

Optional integer - Use this parameter for associating the unsubscribe stats with a connection ID in case of a transactional mailing ID being used

Example

POST URL: https://api.ongage.net/<list_id>/api/v2/contacts/change_status

{
 "list_id": 1,
 "change_to":"remove",
 "emails": [
  "email1@gmail.com",
  "email2@gmail.com",
  "email3@gmail.com"
 ]
}

Response

Version 2

Key	Description

Key	Description
`rows`	Count of emails provided
`success`	Contacts count succeed to change status
`success_emails`	List of all contact emails that changed successfully, with their contact IDs
`failed`	Contacts count failed to change status
`failed_emails`	List of all contact emails that failed, with the failed reasons

Version 1 - (POST /api/contacts/remove) - Deprecated

Key	Description

Key	Description
`rows`	Count of emails provided
`success`	Contacts count succeed to change status
`failed`	Contacts count failed to change status
`results_by_domain`	List of all domains that changed
`removed_contact_ids`	List of all contacts IDs that removed - For "remove" / "bounce" / "complaint"
`contact_ids`	List of all contacts IDs that changed - For "resubscribe" / "soft_bounce" or "unsubscribe"
`success_contacts`	List of all contact emails that were changed successfully
`failed_contacts`	List of all contact emails that failed, grouped by the failed reasons
`success_contacts`	Contacts count failed to change status

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).

Request

email

Required string - Existing contact email address

new_email

Required string - New email address

Example

PUT URL: https://api.ongage.net/<list_id>/api/contacts/change_email

{ "email": "john@doe.com", "new_email": "john@doe.org" }

Response

Key	Description

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/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

{ "contact_id": "4e803cc458a741c010000000" }

contact_ids

Optional array - list of contact IDs

{ "contact_ids": ["4e803cc458a741c010000000", "12e93cc458a741c010000000"] }

Response

The response will include deleted contact fields.

Error Codes

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

Request

email

Required string - Email address

Please note that the time zone is not supported as yet and GMT will be used.

Response Example

{
  "metadata":{
    "error":false
  },
  "payload": {
    "1001":{
      "list_id":1001,
      "list_type":"sending",
      "status":"Active",
      "fields":{
        "first_name":"Nathalie",
        "last_name":"Mon Amour",
        "company":"Telecom",
        "title":"Sales Manager",
        "country":"France",
        "gender":"f"
      }
    },
    "1002":{
      "list_id":1002,
      "list_type":"sending",
      "status":"Unsubscribe",
      "fields":{
        "first_name":"Nathalie",
        "last_name":"Mon Amour",
        "area_of_interest":"Travel",
        "city":"Paris",
        "country":"France",
        "gender":"f"
      },
      "unsubscribe_date": 1453718037
    },
    "1003":{
      "list_id":1003,
      "list_type":"sending",
      "status":"Bounced",
      "fields":{
        "first_name":"Nathalie",
        "last_name":"Mon Amour",
        "country":"France",
        "gender":"f"
      },
      "bounce_date": 1453718037
    },
  }
}