{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/identify/:site_id","auth":"required","examples":{"codes":[]},"method":"post","params":[{"name":"primary.email","type":"string","default":"","desc":"The email address of the user.","required":false,"in":"body","ref":"","_id":"56cf64308acacb13008148c4"},{"name":"primary.bsin","type":"string","default":"","desc":"The Boomtrain identifier returned from a previous identify call for this person.","required":false,"in":"body","ref":"","_id":"56cf64308acacb13008148c3"},{"name":"primary.user_id","type":"string","default":"","desc":"Your internal user ID for the identified person","required":false,"in":"body","ref":"","_id":"56cf64308acacb13008148c2"},{"name":"site_id","type":"string","default":"","desc":"The Boomtrain identifier for your site.","required":false,"in":"path","ref":"","_id":"57b633aea8c0910e002ca42e"}],"results":{"codes":[{"name":"","code":"{\n    \"data\": {\n        \"bsin\": \"FxLPMpYUqOOiSJWXUfV/isF8y6o//2r40uQ4o4riaLvfQKlQtdg1L42/6iqjQLDH3qU/EUvWm9xVcSgLCQu4iQ==\",\n        \"email\": \"user:::at:::example.com\",\n        \"site_id\": \"your-site\",\n        \"user_id\": \"user123\"\n    }\n}","language":"json","status":200}]},"settings":"56ca06cc5a10e20d005b8af0"},"next":{"description":"","pages":[]},"title":"Get a Boomtrain Identifier for a Person","type":"endpoint","slug":"get-a-boomtrain-identifier","excerpt":"Returns the Boomtrain identifier for the specified user, given zero or more other identifiers. This route will also create a person record for identified users who do not yet have a person record.","body":"The `POST /identify` routes serves two purposes: to give the caller an identifier for a person, and to manage people records based on the information given.\n\nNote that at least one of `primary.bsin`, `primary.email`, or `primary.user_id` must be present in the request body, though any or all of them may be empty (e.g. `{\"bsin\":\"\"}`).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Identification of People\"\n}\n[/block]\nFor each identifier (which is guaranteed to have at most one record associated with it), we will check to see if it corresponds to a known person record. After looking up each identifier:\n\n* If no existing records are found, the route returns a new identifier that represents the beginning of this person's history.\n* If one record is found, the route returns an identifier that represents that person.\n* If more than one record is found, the route returns an identifier that represents the record with the highest priority according to the following chart:\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Priority of Identifiers\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HIGHEST PRIORITY\",\n    \"h-1\": \"→\",\n    \"h-2\": \"LOWEST PRIORITY\",\n    \"0-0\": \"user_id\",\n    \"0-1\": \"email\",\n    \"0-2\": \"bsin\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Management of Person Records\"\n}\n[/block]\nIn order to simplify the management of person records, this route also merges and updates person records according to the following logic:\n\nAfter the aforementioned lookup on each identifier,\n\n* If no existing records were found, the route creates a new record with all of supplied identifiers in it. \n\n* If one record was found, the route will add any of the supplied identifiers that are empty in the found record to it. Note that currently it will NOT overwrite any identifiers that exist in that record, even if they are different.\n\n* If more than one record was found, the route will attempt to merge all records that were found based on lower priority identifiers per the above chart, into the record of highest priority. Any records that are merged into a new record will be aliased to that new record.","updates":[],"order":4,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"57b632cb48b2d2170047efa1","parentDoc":null,"project":"56aff08c3a5b810d00745d99","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["56aff08d3a5b810d00745d9d","56aff24f3a5b810d00745da0","56aff25dbc304a0d00ace207","56aff287e0b1e40d00c53798","56aff2b260a37a0d00ed8883","56aff2b8e0b1e40d00c53799","56aff2bd5b1f01170014dc7b","56aff2c9d21e9c0d00b62993","56aff493aef9a21700da0e67","56aff4ce1486990d009c0f64","56aff4da5b1f01170014dc7d","56aff4dfe0b1e40d00c537a2","56aff4e59d32e30d0006d3e9","56aff4e91486990d009c0f65","56aff4f93a5b810d00745da2","56aff4fe9d32e30d0006d3ea","56b91c7ab1e03e0d001057c5","56c4f51aba4a540d0091b9a2","56cd09488c4a331d002c1e44","56d4ec4773dcd20b00fb8769","56e79bc515f96b2200878e54","56ec25c538ff1d2200d56cc2","56ec3a6f36bc8e0e00f190c8","56ec3e308ea7ce0e00a3d8b0","5724d8fe4255580e005938b2","5724dc842ad0bc1700122803","5776ef2a04f7500e0095dc37","57ab9f70b5e8742000e17eb9","57d7117646dcc30e007dd21f","58e6abd5b1eece19008b7d31","59288c65e2653627003e1221","5a8f4797a44f8600128e75ee","5bbf8833eb416300039a2c14","5ea811617bf4b5007328a0af"],"_id":"56aff08c3a5b810d00745d9c","project":"56aff08c3a5b810d00745d99","releaseDate":"2016-02-01T23:55:56.544Z","__v":34,"createdAt":"2016-02-01T23:55:56.544Z"},"category":{"sync":{"isSync":false,"url":""},"pages":["56d4ec8573dcd20b00fb876a"],"title":"Server-Side Integration REST API","slug":"authorization","order":3,"from_sync":false,"reference":true,"_id":"56d4ec4773dcd20b00fb8769","__v":1,"version":"56aff08c3a5b810d00745d9c","createdAt":"2016-03-01T01:11:35.547Z","project":"56aff08c3a5b810d00745d99"},"__v":2,"createdAt":"2016-08-18T22:12:27.899Z","githubsync":"","user":"566887ff8639090d00759415"}

postGet a Boomtrain Identifier for a Person

Returns the Boomtrain identifier for the specified user, given zero or more other identifiers. This route will also create a person record for identified users who do not yet have a person record.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

site_id:
string
The Boomtrain identifier for your site.

Body Params

primary.email:
string
The email address of the user.
primary.bsin:
string
The Boomtrain identifier returned from a previous identify call for this person.
primary.user_id:
string
Your internal user ID for the identified person

Result Format


Documentation

The `POST /identify` routes serves two purposes: to give the caller an identifier for a person, and to manage people records based on the information given. Note that at least one of `primary.bsin`, `primary.email`, or `primary.user_id` must be present in the request body, though any or all of them may be empty (e.g. `{"bsin":""}`). [block:api-header] { "type": "basic", "title": "Identification of People" } [/block] For each identifier (which is guaranteed to have at most one record associated with it), we will check to see if it corresponds to a known person record. After looking up each identifier: * If no existing records are found, the route returns a new identifier that represents the beginning of this person's history. * If one record is found, the route returns an identifier that represents that person. * If more than one record is found, the route returns an identifier that represents the record with the highest priority according to the following chart: [block:api-header] { "type": "basic", "title": "Priority of Identifiers" } [/block] [block:parameters] { "data": { "h-0": "HIGHEST PRIORITY", "h-1": "→", "h-2": "LOWEST PRIORITY", "0-0": "user_id", "0-1": "email", "0-2": "bsin" }, "cols": 3, "rows": 1 } [/block] [block:api-header] { "type": "basic", "title": "Management of Person Records" } [/block] In order to simplify the management of person records, this route also merges and updates person records according to the following logic: After the aforementioned lookup on each identifier, * If no existing records were found, the route creates a new record with all of supplied identifiers in it. * If one record was found, the route will add any of the supplied identifiers that are empty in the found record to it. Note that currently it will NOT overwrite any identifiers that exist in that record, even if they are different. * If more than one record was found, the route will attempt to merge all records that were found based on lower priority identifiers per the above chart, into the record of highest priority. Any records that are merged into a new record will be aliased to that new record.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}