/subscribers

Events Subscribers

A subscriber is an identity that can be used by Manheim API customers to create subscriptions to receive events. Creating a subscriber is the first step toward event notification.

The purpose of a subscriber includes the following:

Subscriber information contains a callback url to which the events will be posted. This is a mandatory information for posting events.
Subscriber information contains an email for the customer. This is required to provide error notification.
Subscriber information contains headers that will be posted with the event body to the callback url.
Customer is provided with subscriber id (as response) on successful creation of subscriber. This can be used later to create subscriptions as well as retrieve subscriber information for callback, email id, headers, and status.

The Subscribers API endpoints allow customers to create & manage subscribers. Subscriber information can be updated, deleted, deactivated, reactivated, or retrieved by the customer as needed. An API customer can create a maximum of 5 subscriber IDs to group subscriptions based on the customer's business needs and preferences.

NOTE: External customers sending requests to this API with the client_credentials grant type must use an access token obtained from the current token endpoint (https://api.manheim.com/oauth2/token). This applies to all API methods for creating, updating, retrieving, or deleting subscribers.

URLs and Environments

The base URL for the Subscribers API is /subscribers. This document describes each method endpoint starting with this base URL.

Actual requests will require the protocol and host URL for one of the Manheim environments:

QA: https://integration1.api.manheim.com
Pre-Production: https://uat.api.manheim.com
Production: https://api.manheim.com

See [API Access and Environments]](#/pages/accessAndEnvironments "API Access and Environments") for more information about Manheim API environments.

Creating a Subscriber

Endpoint

POST /subscribers

Description

The endpoint is used to create the subscriber.
Customer is required to execute a POST to the endpoint to create a subscriber with required data.

Fields required

Field	Type	Required	Notes
callback	String	REQUIRED	URL at which the events will be posted. The URL must use the secure HTTPS protocol
emails	String	REQUIRED	Email address to receive error notification in case of missed events. Format to provide : [email1, email2]. One email id is mandatory, customer can provide more if required.
headers	n/a	OPTIONAL	Headers can be included by the customer for authentication or other purpose. Events posted on the callback will have header information if provided by the customer.
inactive	Boolean	n/a	Field values: false or true. Field value false signifies that subscriber is active. Field value set as true means inactive subscriber that inhibits flow of events for underlying subscriptions. By default it is set as false & customer does not require to set this while creating subscriber.

Example for creating Subscriber

POST https://api.manheim.com/subscribers

{
  "callback" : "https://environment.process.com/ABC",
  "headers" : {"header1" : "headerval1"},
  "emails" : ["someone@company.com"]
}

Common Return Codes for the endpoint

201 Created: Success. Subscriber is created successfully. Customer will receive subscriber id as response( part of location href).
400 Bad Request: Error. The error could mean any of the following:
- Number of subscribers has exceeded the set limit.
- Malformed JSON error.
- Required field attribute is missing from the request.

Updating a Subscriber

Endpoint

POST /subscribers/id/ID

Description

The endpoint is used for updating information for the existing subscriber.
On successful update, events will be posted per the new information provided.
Customer is required to execute a POST to the endpoint for the specific subscriber id with the fields that need to be updated.
Below fields can be updated for a subscriber.
- callback:
  - HTTP url to receive events.
  - On successful callback update, events will be posted to the new url.
- email id:
- The email address to receive error notification.
- headers:
- Header field that customer provides.
- This information will be send as part of event posted to callback.
- Customer can choose to reset field as null in case it is not required as part of events.
- inactive:
- The field is used to deactivate & reactivate subscriber.
- Customer can set the field as true to deactivate subscriber.
- Upon subscriber deactivation, events related to underlying subscription are no longer posted to callback.
- Customer can set the field as false to reactivate the subscriber.
- Upon subscriber reactivation, events related to underlying subscription are posted to callback.
- By default, the field is set as false - subscriber is in active status.
- To remove a particular field from the subscriber, pass in a null value.

Example for updating Subscriber

POST https://api.manheim.com/subscribers/id/ID

{
  "callback" : "https://environment.process.com/ABC",
  "headers" : {"header1" : "headerval1"}
}

Common Return Code

200 Ok: PARTIAL SUCCESS. Some fields, including the updatedOn timestamp, have been updated, but at least one field could not be updated do to an invalid or malformed value supplied. Look for the errors object in the response body, for example:
```
{
  "errors" : [
    {
      "property" : "headers",
      "message" : "invalid value for headers",
      "developerMessage" : "invalid value for headers"
    }
  ]
}
```
204 No Content: SUCCESS. A successful response indicating that the required fields for the given subscriber is updated.
400 Bad Request: ERROR:. One or more fields cannot be updated.
403 Forbidden: ERROR:. The user is not authorized to modify this subscriber.
404 Not Found: ERROR. The requested subscriber was not found.

Retrieving One or All Subscriber(s)

Endpoint

GET /subscribers/id/ID

GET /subscribers/mine

Description

The endpoints are used to retrieve information for existing subscriber.
Retrieval by subscriber id endpoint provides information for the particular subscriber
Retrieval by mine will return information for all the subscribers (as a collection) that a particular customer has created.
Customer is required to execute a GET to the endpoints to receive the required information.

Fields retrieved for the subscriber(s)

Field	Type	Notes
href	String	Subscriber id href
callback	String	Callback url where Eventer will publish events
headers	n/a	Headers (optional) if provided by the customer while creating the subscriber
emails	String	Email ID provided
inactive	Boolean	By default set to "false". When "true" subscriber is inactive with no events
errorEmailLastSent	Date	System-generated; time stamp for most recent error email sent
errorEmailFrequency	Integer	System-generated; interval between error emails, in hours; set by Manheim
createdOn	Date	System-generated; time stamp for when the subscriber was first created
updatedOn	Date	System-generated; time stamp for when the subscriber was last updated

Example for retrieving Subscriber

Retrieval by https://api.manheim.com/subscribers/id/ID endpoint

GET https://api.manheim.com/subscribers/id/ID

Response

{
    "href": "https://api.manheim.com/subscribers/id/973eb924-37b0-11e5-a1ae-3d16aabb333e",
    "callback": "https://environment.process.com/ABC",
    "headers": "{\"HEADER1\":\"HeAdEr1-VaL\",\"MYAUTH-CUSTOM\":\"Bearer ZDKDKM5XMYLQ8DBAGT8T\",\"COOKIE\":\"ZDKDKM5XMYLQ8DBAGT8TIKFGUJEHOTHC4QUF7JJF2WIZVCNFSTMYDLEDOL22==\"}",
    "email": "someone.lastname@manheim.com",
    "inactive": false,
    "errorEmailLastSent": "2015-07-31T18:19:49.000Z",
    "errorEmailFrequency": 24,
    "createdOn": "2015-07-31T18:18:49.591Z",
    "updatedOn": "2015-07-31T18:18:49.591Z"
}

Retrieval by https://api.manheim.com/subscribers/mine endpoint

GET https://api.manheim.com/subscribers/mine

Response

{
	"href": "https://api.manheim.com/subscribers/mine",
	    "items": [
	        {
	            "href": "https://api.manheim.com/subscribers/id/9ab64980-346f-11e5-9144-295cebb2314d3243",
	            "callback" : "https://environment.process.com/ABC",
	            "headers": "{\"authorization\":\"Basic aWZzOil9dH1MSjM0SVpsNWJMKg==\"}",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-27T14:56:04.632Z",
	            "updatedOn": "2015-07-27T14:56:04.632Z"
	        },
	        {
	            "href": "https://api.manheim.com/subscribers/id/50d78210-3772-11e5-9b84-6907426233b4",
	            "callback" : "https://environment.process.com/ABC",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-31T10:53:02.676Z",
	            "updatedOn": "2015-07-31T10:53:02.676Z"
	        },
	        {
	            "href": "https://api.manheim.com/subscribers/id/988532ec-3772-11e5-ab48-636029weqesd",
	            "callback" : "https://environment.process.com/ABC",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-31T10:55:02.933Z",
	            "updatedOn": "2015-07-31T10:55:02.933Z"
	        },
	        {
	            "href": "https://api.manheim.com/subscribers/id/e01ac61c-3772-11e5-a3ce-631wqreerfre",
	            "callback" : "https://environment.process.com/ABC",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-31T10:57:03.031Z",
	            "updatedOn": "2015-07-31T10:57:03.031Z"
	        },
	        {
	            "href": "https://api.manheim.com/subscribers/id/9c07a810-378f-11e5-b922-1d361d3e32e",
	            "callback" : "https://environment.process.com/ABC",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-31T14:22:44.226Z",
	            "updatedOn": "2015-07-31T14:22:44.226Z"
	        },
	        {
	            "href": "https://api.manheim.com/subscribers/id/5c81cdfc-3793-11e5-8fc2-050324325r43",
	            "callback" : "https://environment.process.com/ABC",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-31T14:49:35.639Z",
	            "updatedOn": "2015-07-31T14:49:35.639Z"
	        }
	        {
	            "href": "https://api.manheim.com/subscribers/id/973eb924-37b0-11e5-a1ae-3d16ewwqeqwq",
	            "callback" : "https://environment.process.com/ABC",
	            "headers": "{\"HEADER1\":\"HeAdEr1-VaL\",\"MYAUTH-CUSTOM\":\"Bearer ZDKDKM5XMYLQ8DBAGT8T\",\"COOKIE\":\"ZDKDKM5XMYLQ8DBAGT8TIKFGUJEHOTHC4QUF7JJF2WIZVCNFSTMYDLEDOL22==\"}",
	            "email": "someone.lastname@manheim.com",
	            "inactive": true,
	            "errorEmailLastSent": "2015-07-31T18:19:49.000Z",
	            "errorEmailFrequency": 24,
	            "createdOn": "2015-07-31T18:18:49.591Z",
	            "updatedOn": "2015-07-31T18:18:49.591Z"
	        }
	    ]
	}
}

Common Return Codes for the endpoint

200 OK: SUCCESS. A successful response with the requested subscriber information
404 Not Found: ERROR: the requested subscriber by id is not found.
200 ok with empty array ([]): SUCCESS. A successful response with empty collection as the particular customer has no subscriber.

Deleting a Subscriber

Endpoints

DELETE /subscribers/id/ID

DELETE /subscribers/id/ID?force=true

Description

The endpoint is used to delete subscriber.
In order to delete a subscriber all underlying subscriptions need to be deleted.
On successful delete of the subscriber, there will be no event flow to callback for related subscriptions.
Subscriber is required to execute a Delete to the endpoint for the particular subscriber ID.
To delete subscriber & related subscriptions at one go, parameter force with value as true needs to be passed (as provided in code block above).

Common Return Codes for the endpoint

204 No Content: A successful response that the subscriber has been deleted.
400 Bad Request: ERROR:. The requested subscriber cannot be deleted.
403 Forbidden: ERROR:. The user is not allowed to delete the subscriber.
404 Not Found: ERROR:. The requested subscriber is not found.

Subscriber Validation- Test Event

When a subscriber is created or updated, the eventing system checks if it can set connection & talk to the customer's callback to publish events.
System sends a test event to the customer's callback to validate it.

Test event Template format:

{
    "href": "https://test.api.manheim.com/events/id/test_event_uuid",
    "eventType": "TEST.EVENT",
    "body": {
        "key": "value"
    },
    "createdOn": "2018-04-11T17:40:06.598Z",
    "subscription": {
        "href": "https://test.api.manheim.com/subscriptions/id/test_subscription_uuid"
    },
    "subscriber": {
        "href": "https://test.api.manheim.com/subscribers/id/test_subscriber_uuid"
    }
}

Validation when a Subscriber is created.

Customer provides required fields to create new subscriber. After initial front-end field validation, below test event is sent to callback url to ascertain that a connection can be made for event publishing.
If the event is successfully delivered to the callback with 2XX HTTP response, the subscriber is successfully created with "inactive" field set as "false". It is now ready to receive event notifications on the callback url.
If the test event is unsuccessful on the callback with a non 2XX response, the subscriber is created with "inactive" field = "true". & cannot receive events on callback.
Active Subscriptions can be created for inactive subscriber.
While subscriber is inactive, Events matching to Subscription cannot be published to callback but can be retrieved from the /events endpoints doing a GET.
When a customer re-sets the inactive field to "false" for the subscriber, test event is re-sent to the callback to re-validate the connections. -In addition to receiving business events on callback, customers are required to handle the test event as well.

Example of test event validation failure at callback:

Customer creates Subscriber:

{
 "callback" : "https://postman-echo.com/status/202",
 "emails" : ["someone@company.com"]
}

Test Event is sent to the mentioned callback (connection not established with callback):

Test Event Template:

{
    "href": "https://test.api.manheim.com/events/id/test_event_uuid",
    "eventType": "TEST.EVENT",
    "body": {
        "key": "value"
    },
    "createdOn": "2018-04-11T17:40:06.598Z",
    "subscription": {
        "href": "https://test.api.manheim.com/subscriptions/id/test_subscription_uuid"
    },
    "subscriber": {
        "href": "https://test.api.manheim.com/subscribers/id/test_subscriber_uuid"
    }
}

In case of non-2XX response from callback, Subscriber is created with "inactive" = "true":

{
 "errors": [
   {
         "property": "callback",
         "message": "Test callback check failed with the error response: 404. The subscriber was created as inactive",
         "developerMessage": "Use {inactive: false} to reactivate subscriber."
   }
 ]
}

Example of test event validation success on callback:

Customer creates Subscriber:

{
  "callback" : "http://company.createdata.XYZ.com/ABC",
  "headers" : {"key":"value24"},
  "emails" : ["someone11@gmail.com"]
}

Test Event is sent to the mentioned callback (connection is successfully established with callback):

Test Event Template:

{
        "href": "https://test.api.manheim.com/events/id/test_event_uuid",
        "eventType": "TEST.EVENT",
        "body": {
                "key": "value"
        },
        "createdOn": "2018-04-11T17:40:06.598Z",
        "subscription": {
                "href": "https://test.api.manheim.com/subscriptions/id/test_subscription_uuid"
        },
        "subscriber": {
                "href": "https://test.api.manheim.com/subscribers/id/test_subscriber_uuid"
        }
}

In case of 200 response from callback, Subscriber is created with "inactive" = "false". Test event is successfully received on callback.

Test Event on callback url:

{
  "body": "{\"href\":\"https://test.api.manheim.com/events/id/test_event_uuid\",\"eventType\":\"TEST.EVENT\",\"body\":{\"key\":\"value\"},\"createdOn\":\"2018-03-01T23:46:04.442Z\",\"subscription\":{\"href\":\"https://test.api.manheim.com/subscriptions/id/test_subscription_uuid\"},\"subscriber\":{\"href\":\"https://test.api.manheim.com/subscribers/id/test_subscriber_uuid\"}}",
  "headers": "{\"HOST\":\"throwitatthewall-prod.elasticbeanstalk.com\",\"X_REAL_IP\":\"10.142.201.33\",\"X_FORWARDED_FOR\":\"52.4.206.249, 10.142.201.33\",\"ACCEPT\":\"*/*\",\"ACCEPT_ENCODING\":\"gzip, deflate\",\"KEY\":\"value24\",\"USER_AGENT\":\"rest-client/2.0.2 (linux-gnu x86_64) ruby/2.3.5p376\",\"X_NEWRELIC_ID\":\"VQcCVlBACQQFV1BTAQA=\",\"X_NEWRELIC_TRANSACTION\":\"PxQFUAMHDgBSAVhSUgIAB1YFFB8EBw8RVU4aUwgOUVNQVl9WBFBSW1IGFU1EVllSVFEHUQQTag==\",\"X_FORWARDED_PORT\":\"80\",\"X_FORWARDED_PROTO\":\"http\"}",
  "url": "neha",
  "timestamp": 1525978552
}

Validation when a Subscriber is updated.

When a customer updates subscriber fields- headers, inactive, callback url, a test event is sent to callback to validate connection & confirm that events flow to the callback.
In case of non-2XX response subscriber is turned off with "inactive" field = "true".
Events will not be published to the callback url.
Customer can do a GET on the /events endpoint to get events result set.
Once the subscriber is fixed, the customer will need to set the "inactive" field to "false" to re-activate the subscriber.
A test event is sent again on re-activation.

Auto-Deactivating a Subscriber

Description

Customer will receive an error email notification when an event is not posted due to non-response callback.
Subscriber will automatically be deactivated if the particular callback continuously errors during event publication for a given time-frame.
On subscriber deactivation, no events will be posted to callback for the underlying subscriptions.
The "inactive" field, part of subscriber is set to "true" on deactivation.
Customer will be send an email notification informing about the auto-deactivation.
Upon issue resolution, customer will be required to reactive the subscriber to receive events for underlying subscriptions.
Customer can reactivate the subscriber by setting the inactive field as false.

/subscribers ​

Events Subscribers ​

URLs and Environments ​

Creating a Subscriber ​

Endpoint ​

Description ​

Fields required ​

Example for creating Subscriber ​

Common Return Codes for the endpoint ​

Updating a Subscriber ​

Endpoint ​

Description ​

Example for updating Subscriber ​

Common Return Code ​

Retrieving One or All Subscriber(s) ​

Endpoint ​

Description ​

Fields retrieved for the subscriber(s) ​

Example for retrieving Subscriber ​

Retrieval by https://api.manheim.com/subscribers/id/ID endpoint ​

Retrieval by https://api.manheim.com/subscribers/mine endpoint ​

Common Return Codes for the endpoint ​

Deleting a Subscriber ​

Endpoints ​

Description ​

Common Return Codes for the endpoint ​

Subscriber Validation- Test Event ​

Validation when a Subscriber is created. ​

Example of test event validation failure at callback: ​

Example of test event validation success on callback: ​

Validation when a Subscriber is updated. ​

Auto-Deactivating a Subscriber ​

Description ​

/subscribers

Events Subscribers

URLs and Environments

Creating a Subscriber

Endpoint

Description

Fields required

Example for creating Subscriber

Common Return Codes for the endpoint

Updating a Subscriber

Endpoint

Description

Example for updating Subscriber

Common Return Code

Retrieving One or All Subscriber(s)

Endpoint

Description

Fields retrieved for the subscriber(s)

Example for retrieving Subscriber

Retrieval by https://api.manheim.com/subscribers/id/ID endpoint

Retrieval by https://api.manheim.com/subscribers/mine endpoint

Common Return Codes for the endpoint

Deleting a Subscriber

Endpoints

Description

Common Return Codes for the endpoint

Subscriber Validation- Test Event

Validation when a Subscriber is created.

Example of test event validation failure at callback:

Example of test event validation success on callback:

Validation when a Subscriber is updated.

Auto-Deactivating a Subscriber

Description