Subscriber v1.2
Add and manage the core data set for a subscriber.
Add and manage the core data set for a subscriber.
Subscribers are at the heart of the Sign-Up.to Permission Marketing API. This endpoint is useful anywhere where you might want to utilise someone's personal details.
list_id
and confirmed
attributes. email
and msisdn
are unique to a subscriber. These fields can be very useful when filtering.Attribute | Type | Filter | Sort | Description |
---|---|---|---|---|
id | int | Yes | Yes | Unique ID of the subscriber. |
bounce_exists | bool | No | No | Whether this subscriber has ever had a bounced email. |
companyname | string/null | No | No | Subscriber's company name. |
confirmed | bool/null | No | No | Whether the subscription to the list specified by list_id is confirmed. |
contact_exists | bool | No | No | Whether this subscriber has ever been contacted. |
country | string/null | No | No | Subscriber's country in ISO-3316-1 format (two character), for example "GB". |
county | string/null | No | No | Subscriber's county. |
daybirth | int/null | No | No | The day of the month of the subscriber's birthday (1-31). |
string | Yes | Yes | Subscriber email address. | |
emailmd5 | string | No | No | MD5 digest of the contents of the "email" attribute. |
emailsuspended | bool | Yes | No | Whether email delivery to the subscriber is currently suspended. |
firstname | string/null | No | No | Subscriber's first/given name. |
gender | enum/null | No | No | Either "male" or "female". |
housenumber | string/null | No | No | Subscriber's house number. |
lastname | string/null | No | No | Subscriber's last/family name. |
latestopenip | string/null | No | No | IP address from which the subscriber most recently opened an email. |
list_id | int/null/array | Yes** | No | List ID(s) of the list that the subscriber is subscribed to. |
monthbirth | int/null | No | No | The month of the subscriber's birthday (1-12). |
msisdn | string | Yes | Yes | Subscriber MSISDN (see definition). N.B. This attribute is treated as a string. |
postcode | string/null | No | No | Subscriber's postcode. |
searchexecute_id | int/null | Yes** | No | Unique ID of a stored searchexecute resource. |
smssuspended | bool | Yes | No | Whether SMS delivery to the subscriber is currently suspended. |
streetname | string/null | No | No | Subscriber's street name. |
subscription_count | int | No | No | Number of subscriptions held by this subscriber. |
title | string/null | No | No | Subscriber's title. |
town | string/null | No | No | Subscriber's town. |
yearbirth | int/null | No | No | The four-digit year of the subscriber's birth. |
cdate | decimal | No | Yes | Creation timestamp. |
mdate | decimal | No | No | Last modification timestamp. |
**list_id
and searchexecute_id
are mutually exclusive.
If searchexecute_id
is present, it must refer to a searchExecute resource where store
is true and the data stored has not expired (stored data expires 7 days after creation).
If filtering by list_id
, subscription_count
will be "null" and confirmed
will be "true"/"false". For all other filters subscription_count
will be an integer and confirmed
will be "null".
If your company is restricting access to folders and the user is not an admin, the collection of available subscribers will be constrained to visible subscriptions.
Attribute | Type | Presence | Description |
---|---|---|---|
id | int | Optional | Unique ID of the subscriber. |
string | Optional | Subscriber email address. | |
emailsuspended | bool | Optional | Whether email delivery to the subscriber is currently suspended. |
list_id | int/null/array | Optional** | List ID(s) of the list that the subscriber is subscribed to. |
msisdn | string | Optional | Subscriber MSISDN (see definition). N.B. This attribute is treated as a string. |
searchexecute_id | int/null | Optional** | Unique ID of a stored searchexecute resource. |
smssuspended | bool | Optional | Whether SMS delivery to the subscriber is currently suspended. |
Attribute | Type | Presence | Description |
---|---|---|---|
companyname | string/null | Optional | Subscriber's company name. |
confirmed | bool/null | Required | Whether the subscription to the list specified by list_id is confirmed. |
country | string/null | Optional | Subscriber's country in ISO-3316-1 format (two character), for example "GB". |
county | string/null | Optional | Subscriber's county. |
daybirth | int/null | Optional | The day of the month of the subscriber's birthday (1-31). |
string | Required* | Subscriber email address. | |
firstname | string/null | Optional | Subscriber's first/given name. |
gender | enum/null | Optional | Either "male" or "female". |
housenumber | string/null | Optional | Subscriber's house number. |
lastname | string/null | Optional | Subscriber's last/family name. |
list_id | int/null/array | Required | List ID(s) of the list that the subscriber is subscribed to. |
monthbirth | int/null | Optional | The month of the subscriber's birthday (1-12). |
msisdn | string | Required* | Subscriber MSISDN (see definition). N.B. This attribute is treated as a string. |
postcode | string/null | Optional | Subscriber's postcode. |
streetname | string/null | Optional | Subscriber's street name. |
title | string/null | Optional | Subscriber's title. |
town | string/null | Optional | Subscriber's town. |
yearbirth | int/null | Optional | The four-digit year of the subscriber's birth. |
*POST requires either email
, msisdn
or both.
A new subscriber must be submitted with details of their first subscription. After this point the subscriber and their subscriptions can be managed independently through the appropriate endpoints.
Subscriber records cannot be created if email
or msisdn
are present in your 'Do Not Contact List'.
Because email
and msisdn
attributes are unique, a request containing known values will fail.
Attribute | Type | Presence | Description |
---|---|---|---|
id | int | Required | Unique ID of the subscriber. |
companyname | string/null | Optional | Subscriber's company name. |
country | string/null | Optional | Subscriber's country in ISO-3316-1 format (two character), for example "GB". |
county | string/null | Optional | Subscriber's county. |
daybirth | int/null | Optional | The day of the month of the subscriber's birthday (1-31). |
string | Optional | Subscriber email address. | |
emailsuspended | bool | Optional | Whether email delivery to the subscriber is currently suspended. |
firstname | string/null | Optional | Subscriber's first/given name. |
gender | enum/null | Optional | Either "male" or "female". |
housenumber | string/null | Optional | Subscriber's house number. |
lastname | string/null | Optional | Subscriber's last/family name. |
monthbirth | int/null | Optional | The month of the subscriber's birthday (1-12). |
msisdn | string | Optional | Subscriber MSISDN (see definition). N.B. This attribute is treated as a string. |
postcode | string/null | Optional | Subscriber's postcode. |
smssuspended | bool | Optional | Whether SMS delivery to the subscriber is currently suspended. |
streetname | string/null | Optional | Subscriber's street name. |
title | string/null | Optional | Subscriber's title. |
town | string/null | Optional | Subscriber's town. |
yearbirth | int/null | Optional | The four-digit year of the subscriber's birth. |
Custom data held against a subscriber can be managed via subscriberProfileData and subscriberProfileField.
Attribute | Type | Presence | Description |
---|---|---|---|
id | int | Required | Unique ID of the subscriber. |
Also issues DELETE on any subscriberProfileData, subscriptions and pending automation actions which reference the subscriber's id
.
Code | Subcode | Message | Description |
---|---|---|---|
400 | 6 | Subscriber email is on the Do Not Contact list: $email | The subscriber's email address has been found on the company/global Do Not Contact list. |
400 | 7 | Subscriber email domain is on the Do Not Contact list: $email | The subscriber's email address domain has been found on the company Do Not Contact list. |
400 | 8 | Subscriber email is on the watch list: $email | The subscriber's email address prefix or domain has been found on the Global Watch List. |
400 | 9 | Subscriber MSISDN is on the Do Not Contact list: $msisdn | The subscriber's MSISDN has been found on the company/global Do Not Contact list. |
409 | 13 | Subscriber attribute 'email|msisdn' cannot be modified to the value '$email|$msisdn'. Please POST as a new subscriber. | If a user makes a PUT request where email or msisdn is set to a value that matches another subscriber's data, but the existing subscriber is not accessible by the user, this error will be returned. In this instance, it will be necessary for the user to POST a new subscriber with the requested email or msisdn. |
Please see error handling for more information on error codes.
Have you seen our example of this endpoint being used with other endpoints?
{ "id": 87654321, "bounce_exists": false, "companyname": "JSmith Ltd", "confirmed": false, "contact_exists": true, "country": "GB", "county": "Surrey", "daybirth": 12, "email": "mailbox@example.com", "emailmd5": "0123456789abcdef0123456789abcdef", "emailsuspended": false, "firstname": "John", "gender": "male", "housenumber": "10", "lastname": "Smith", "latestopenip": "44.131.219.205", "list_id": 12345, "monthbirth": 3, "msisdn": "447123456789", "postcode": "GU22 7PY", "searchexecute_id": null, "smssuspended": false, "streetname": "Pie street", "subscription_count": 3, "title": "Mr", "town": "Woking", "yearbirth": 1960, "cdate": 1234966741, "mdate": 1234966741 }