Subscribe

This web service creates and links subscription profiles, which could be used for example as part of an email newsletter subscription.

A subscription profile can be linked to one or multiple device identified profiles. A device identified profile can be of a site visitor and identified customer.

Request

Name Description
HTTP-Method GET
Content-Type None
Path /op/[pipeline]/v1/subscribe/ 
GET /op/[pipeline]/v1/subscribe/?em=[encryptedEmail]

Request Parameters

Name Value Required Description
em Base64Url encoded encrypted identifier Yes Encrypted identifier, for example E-Mail. The identifieris decrypted and validated, then hashed and persisted in the DB. Also it is linked to the UMDID, if provided.
umdid cookie No UMDID as obtained from umdid cookie.

em-Parameter

The em parameter contains an encrypted and Base64Url encoded identifier, for example an E-Mail.

The identifier must be encrypted as follows:

Name Description
Cipher AES
Key Size 256 Bit
Mode of Operation Galois/Counter Mode (GCM)
Padding None
IV Random 12 Byte IV. The IV must never be used twice.
Ciphertext Same size as plaintext
GCM authentication tag 16 Byte

The encrypted identifier is formed by concatenating the bytes of the triplet (IV, ciphertext, GCM-tag). Finally the encrypted identifier must be Base64Url encoded.

Response HTTP Status Codes

Code Name Description
200 OK The subscription was successful.
400 Bad Request The request was malformed. For example no subscription ID is provided or the provided encrypted subscription ID is not decryptable.
404 Not Found Endpoint has not been configured.
500 Internal Server Error An error occurred when processing the request. For example the DB access timed out.

The subscription was successful.

Response Body for Success Case

Content-Type: application/json

A JSON object with the following fields:

Field Name Type Description
ok Boolean Always true for success. Example: {"ok":true}

Response Body for Error Case

Content-Type: application/json

A JSON object with the following fields:

Field Name Type Description
ok Boolean Always false for errors. Example: {"ok":false}
errorMessage String Description of error. Examples:
  • {"ok":false,"errorMessage":"Field 'em' contains unauthenticated ID value: ''"}
  • {"ok":false,"errorMessage":"Field 'em' has invalid ID value: '1'"}

Example Curls

Subscribe with an encrypted email ID, but no UMDID device identifier:

curl "https://[domain]/op/[pipeline]/v1/subscribe/?em=[encryptedEmail]"

Subscribe with an encrypted email ID and an UMDID device identifier:

curl -b "umdid=[base64umdid]" "https://[domain]/op/[pipeline]/v1/subscribe/?em=[encryptedEmail]"