diff --git a/src/personas/profile-api.md b/src/personas/profile-api.md index 07f6f0c9e4..3b74843931 100644 --- a/src/personas/profile-api.md +++ b/src/personas/profile-api.md @@ -64,15 +64,14 @@ Your namespace ID can be found here: [https://app.segment.com/goto-my-workspace/ 2. Create your Postman GET request to query the user's event's history: i. The URL is: - - https://profiles.segment.com/v1/spaces//collections/users/profiles//events + `https://profiles.segment.com/v1/spaces//collections/users/profiles//events` - ii. Replace with your own namespace id found here: + ii. Replace `` with your own namespace id found here: [https://app.segment.com/goto-my-workspace/personas/spaces/default/settings/api-access](https://app.segment.com/goto-my-workspace/personas/spaces/default/settings/api-access) - iii. Replace **** with your external id type and id pair from step B + iii. Replace `` with your external id type and id pair from step B iv. Copy your **Access Secret** from step (A) into the _Basic Auth > Username field_. Leave Password empty. @@ -93,53 +92,50 @@ Your namespace ID can be found here: [https://app.segment.com/goto-my-workspace/ You can query directly by a user's email or user_id: - https://profiles.segment.com/v1/spaces//collections/users/profiles/email:user@gmail.com/events +`https://profiles.segment.com/v1/spaces//collections/users/profiles/email:user@gmail.com/events` - https://profiles.segment.com/v1/spaces//collections/users/profiles/user_id:u1234567/events +`https://profiles.segment.com/v1/spaces//collections/users/profiles/user_id:u1234567/events` **External IDs** You can query all of a user's external ids (email, anonymous_id, user_id): - - https://profiles.segment.com/v1/spaces//collections/users/profiles/email:user@gmail.com/external_ids +`https://profiles.segment.com/v1/spaces//collections/users/profiles/email:user@gmail.com/external_ids` **Traits** You can query a user's traits (first_name, last_name, ...): - https://profiles.segment.com/v1/spaces//collections/users/profiles//traits +`https://profiles.segment.com/v1/spaces//collections/users/profiles//traits` By default, we will include 20 traits. You can return up to 200 traits by appending `?limit=200` to the querystring. If you wish to return a specific trait, append `?include={trait}` to the querystring (eg `?include=age`). **Metadata** You can query all of a user's metadata (created_at, updated_at, ...): - https://profiles.segment.com/v1/spaces//collections/users/profiles//metadata +`https://profiles.segment.com/v1/spaces//collections/users/profiles//metadata` **Search an account profile** If you are sending group calls to Segment, you can now access your account profiles as well. You can retrieve your account traits, computed traits, and audience traits by querying the `group_id` you are interested in: - https://profiles.segment.com/v1/spaces//collections/accounts/profiles/group_id:12345/traits +`https://profiles.segment.com/v1/spaces//collections/accounts/profiles/group_id:12345/traits` **Search for linked users or accounts** If you are looking to find all the users linked to an account, you can search for an account's linked users, or a user's linked accounts. - https://profiles.segment.com/v1/spaces//collections/accounts/profiles/group_id:12345/links +`https://profiles.segment.com/v1/spaces//collections/accounts/profiles/group_id:12345/links` ### cURL You can also request via cURL: +```bash +export SEGMENT_ACCESS_SECRET="YOUR_API_ACCESS_TOKEN_SECRET_HERE" - export SEGMENT_ACCESS_SECRET="YOUR_API_ACCESS_TOKEN_SECRET_HERE" - - - curl https://profiles.segment.com/v1/spaces//collections/users/profiles//events -u $SEGMENT_ACCESS_SECRET: - - +curl https://profiles.segment.com/v1/spaces//collections/users/profiles//events -u $SEGMENT_ACCESS_SECRET: +``` ## API Reference @@ -164,9 +160,10 @@ You can create your Access Secret in your Personas Settings page. We strongly re When making requests to the Profile API, use the Access Secret as the basic authentication username and keep the password blank. - - curl https://profiles.segment.com/v1/spaces//collections/users/profiles - -u $SEGMENT_ACCESS_SECRET: +```bash +curl https://profiles.segment.com/v1/spaces//collections/users/profiles + -u $SEGMENT_ACCESS_SECRET: +``` ### Errors @@ -186,12 +183,14 @@ Segment uses conventional HTTP response codes to indicate the success or failur **Error Body** +```js { "error": { "code": "validation_error", "message": "The parameter `collection` has invalid character(s) `!`" } } +``` | **Code** | **Message** | | ------------------------- | -------------| @@ -224,18 +223,17 @@ All top-level API resources have support for bulk fetches via "list" API methods | `next` | The string cursor that indexes the next page of requests. | | `url` | The URL for accessing this list. | - - #### Request IDs Each API request has an associated request identifier. You can find this value in the response headers, under `Request-Id`. **If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.** - - curl -i https://profiles.segment.com/v1/spaces//collections/users/profiles - HTTP/1.1 200 OK - Date: Mon, 01 Jul 2013 17:27:06 GMT - Status: 200 OK - Request-Id: 1111-2222-3333-4444 +```bash +curl -i https://profiles.segment.com/v1/spaces//collections/users/profiles +HTTP/1.1 200 OK +Date: Mon, 01 Jul 2013 17:27:06 GMT +Status: 200 OK +Request-Id: 1111-2222-3333-4444 +``` ### Routes | **Name** | **Route** https://profiles.segment.com/v1/spaces/:space_id:/ ... | @@ -250,39 +248,45 @@ Each API request has an associated request identifier. You can find this value i Get a single profile's traits within a collection using an `external_id`. For example, two different sources can set a different `first_name` for a user. The traits endpoint will resolve properties from multiple sources into a canonical source using the last updated precedence order. - - GET /v1/spaces//collections//profiles//traits +``` +GET /v1/spaces//collections//profiles//traits +``` **Examples** Here's what it looks to search for a profile's traits by an external id, like by an `email`: - - GET /v1/spaces/lg8283283/collections/users/profiles/email:amir@segment.com/traits +``` +GET /v1/spaces/lg8283283/collections/users/profiles/email:amir@segment.com/traits +``` Or a `user_id`: - - GET /v1/spaces/lg8283283/collections/users/profiles/user_id:u1234/traits +``` +GET /v1/spaces/lg8283283/collections/users/profiles/user_id:u1234/traits +``` **Request** - +```bash curl https://profiles.segment.com/v1/spaces/:namespace_id:/collections/users/profiles//traits -X GET -u $SEGMENT_ACCESS_SECRET: +``` **404 Not Found** +```js { "error": { "code": "not_found", "message": "Profile was not found." } } +``` **200 OK** - +```js { "traits": { "first_name": "Bob", @@ -295,8 +299,11 @@ Or a `user_id`: } } +``` + And when ?**verbose=true** mode on: +```js { "traits": { "first_name": { @@ -316,7 +323,7 @@ And when ?**verbose=true** mode on: "next": "" } } - +``` **Query Parameters** @@ -332,46 +339,51 @@ And when ?**verbose=true** mode on: Get a single profile's external ids within a collection using an `external_id`. - - GET /v1/spaces//collections//profiles//external_ids +``` +GET /v1/spaces//collections//profiles//external_ids +``` **Request** - curl https://profiles.segment.com/v1/spaces/:namespace_id:/collections/users/profiles//external_ids - -X GET - -u $SEGMENT_ACCESS_SECRET: +```bash +curl https://profiles.segment.com/v1/spaces/:namespace_id:/collections/users/profiles//external_ids + -X GET + -u $SEGMENT_ACCESS_SECRET: +``` **404 Not Found** +```js { "error": { "code": "not_found", "message": "Profile was not found." } } +``` **200 OK** - - { - "data": [ - { - "source_id": "GFu4AJc2bE" - "collection": "users", - "id": "1d1cd931-bc7d-4e39-a1a7-61563296fb15", - "type": "cross_domain_id", - "created_at": "2017-11-30T06:05:01.40468Z", - "encoding": "none", - "first_message_id": "ajs-0af8675aa114c759210a76b2baea0a03-clean", - } - ], - "cursor": { - "url": "/v1/spaces/lgJ4AAjFN4/collections/users/profiles/use_RkjG0kW53igMijEISMH0vKBF4sL/external_ids", - "has_more": true, - "next": "map_0vKouKs2XyirgwMO4SmnDGaps7j" - } +```js +{ + "data": [ + { + "source_id": "GFu4AJc2bE" + "collection": "users", + "id": "1d1cd931-bc7d-4e39-a1a7-61563296fb15", + "type": "cross_domain_id", + "created_at": "2017-11-30T06:05:01.40468Z", + "encoding": "none", + "first_message_id": "ajs-0af8675aa114c759210a76b2baea0a03-clean", + } + ], + "cursor": { + "url": "/v1/spaces/lgJ4AAjFN4/collections/users/profiles/use_RkjG0kW53igMijEISMH0vKBF4sL/external_ids", + "has_more": true, + "next": "map_0vKouKs2XyirgwMO4SmnDGaps7j" } - +} +``` **Query Parameters** @@ -387,91 +399,95 @@ Get a single profile's external ids within a collection using an `external_id`. Get a single profile's events within a collection using an `external_id`. - +``` GET /v1/spaces//collections//profiles//events +``` **Request** - +```js curl https://profiles.segment.com/v1/spaces/:namespace_id:/collections/users/profiles//events -X GET -u $SEGMENT_ACCESS_SECRET: +``` **404 Not Found** - { - "error": { - "code": "not_found", - "message": "Profile was not found." - } - } +```js +{ + "error": { + "code": "not_found", + "message": "Profile was not found." + } +} +``` **200 OK** - +```js +{ + "data": [ { - "data": [ + "external_ids": [ + { + "collection": "users", + "type": "user_id", + "id": "c0HN02fNe1", + "encoding": "none" + }, { - "external_ids": [ - { - "collection": "users", - "type": "user_id", - "id": "c0HN02fNe1", - "encoding": "none" - }, - { - "collection": "users", - "type": "cross_domain_id", - "id": "1d1cd931-bc7d-4e39-a1a7-61563296fb15", - "encoding": "none" - } - ], - "context": { - "ip": "73.92.233.78", - "library": { - "name": "analytics.js", - "version": "3.2.5" - }, - "page": { - "path": "/docs/connections/spec/ecommerce/v2/", - "referrer": "https://www.google.com/", - "search": "", - "title": "Spec: V2 Ecommerce Events Documentation - Segment", - "url": "https://segment.com/docs/connections/spec/ecommerce/v2/" - }, - "traits": { - "crossDomainId": "1d1cd931-bc7d-4e39-a1a7-61563296fb15" - }, - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36" - }, - "type": "track", - "message_id": "ajs-1a6064a677b3c16a01b8055c18f16e0b-clean", - "source_id": "CRx5M9uk2p", - "timestamp": "2018-01-05T00:16:35.663Z", - "properties": { - "name": "Docs", - "page_name": "Docs", + "collection": "users", + "type": "cross_domain_id", + "id": "1d1cd931-bc7d-4e39-a1a7-61563296fb15", + "encoding": "none" + } + ], + "context": { + "ip": "73.92.233.78", + "library": { + "name": "analytics.js", + "version": "3.2.5" + }, + "page": { "path": "/docs/connections/spec/ecommerce/v2/", "referrer": "https://www.google.com/", "search": "", - "section": "Spec", "title": "Spec: V2 Ecommerce Events Documentation - Segment", - "topic": "Spec: V2 Ecommerce Events", "url": "https://segment.com/docs/connections/spec/ecommerce/v2/" - }, - "event": "Page Viewed", - "related": { - "users": "use_RkjG0kW53igMijEISMH0vKBF4sL" - } - } - ], - "cursor": { - "url": "/v1/spaces/lgJ4AAjFN4/collections/users/profiles/use_RkjG0kW53igMijEISMH0vKBF4sL/events", - "has_more": true, - "next": "MTUxMzc1NTQzNjg2NzAwMDAwMDo6YWpzLTcyMWFhNzFjNDM2ZWJhOTUyYmI1ZmNiMzJlZWI3MWMzLWNsZWFu" + }, + "traits": { + "crossDomainId": "1d1cd931-bc7d-4e39-a1a7-61563296fb15" + }, + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36" + }, + "type": "track", + "message_id": "ajs-1a6064a677b3c16a01b8055c18f16e0b-clean", + "source_id": "CRx5M9uk2p", + "timestamp": "2018-01-05T00:16:35.663Z", + "properties": { + "name": "Docs", + "page_name": "Docs", + "path": "/docs/connections/spec/ecommerce/v2/", + "referrer": "https://www.google.com/", + "search": "", + "section": "Spec", + "title": "Spec: V2 Ecommerce Events Documentation - Segment", + "topic": "Spec: V2 Ecommerce Events", + "url": "https://segment.com/docs/connections/spec/ecommerce/v2/" + }, + "event": "Page Viewed", + "related": { + "users": "use_RkjG0kW53igMijEISMH0vKBF4sL" } } - + ], + "cursor": { + "url": "/v1/spaces/lgJ4AAjFN4/collections/users/profiles/use_RkjG0kW53igMijEISMH0vKBF4sL/events", + "has_more": true, + "next": "MTUxMzc1NTQzNjg2NzAwMDAwMDo6YWpzLTcyMWFhNzFjNDM2ZWJhOTUyYmI1ZmNiMzJlZWI3MWMzLWNsZWFu" + } +} +``` **Query Parameters** @@ -488,40 +504,44 @@ Get a single profile's events within a collection using an `external_id`. Get a single profile's metadata within a collection using an `external_id`. - +``` GET /v1/spaces//collections//profiles//metadata +``` **Request** - +```bash curl https://profiles.segment.com/v1/spaces/:namespace_id:/collections/users/profiles//metadata -X GET -u $SEGMENT_ACCESS_SECRET: +``` **404 Not Found** - { - "error": { - "code": "not_found", - "message": "Profile was not found." - } - } +```js +{ + "error": { + "code": "not_found", + "message": "Profile was not found." + } +} +``` **200 OK** - - { - "metadata": { - "created_at": "2017-10-23T00:22:42.78Z", - "updated_at": "2018-01-05T00:16:36.919Z", - "expires_at": null, - "first_message_id": "ajs-32ed8dea3980c0c92ed2b8c9c8c5dfb5-clean", - "first_source_id": "GFu4AJc2bE", - "last_message_id": "ajs-1a6064a677b3c16a01b8055c18f16e0b-clean", - "last_source_id": "CRx5M9uk2p", - }, - } - +```js +{ + "metadata": { + "created_at": "2017-10-23T00:22:42.78Z", + "updated_at": "2018-01-05T00:16:36.919Z", + "expires_at": null, + "first_message_id": "ajs-32ed8dea3980c0c92ed2b8c9c8c5dfb5-clean", + "first_source_id": "GFu4AJc2bE", + "last_message_id": "ajs-1a6064a677b3c16a01b8055c18f16e0b-clean", + "last_source_id": "CRx5M9uk2p", + }, +} +``` **Query Parameters** @@ -534,58 +554,61 @@ Get a single profile's metadata within a collection using an `external_id`. Get the users linked to an account, or accounts linked to a user, using an `external_id`. - - GET /v1/spaces//collections//profiles//links +``` +GET /v1/spaces//collections//profiles//links +``` **Request** - +```bash curl https://profiles.segment.com/v1/spaces/:namespace_id:/collections/users/profiles//links -X GET -u $SEGMENT_ACCESS_SECRET: +``` **404 Not Found** - { - "error": { - "code": "not_found", - "message": "Profile was not found." - } - } - +```js +{ + "error": { + "code": "not_found", + "message": "Profile was not found." + } +} +``` **200 OK** - - { - "data": [ - { - "to_collection": "accounts", - "external_ids": [ - { - "id": "ADGCJE3Y8H", - "type": "group_id", - "source_id": "DFAAJc2bE", - "collection": "accounts", - "created_at": "2018-10-06T03:43:26.63387Z", - "encoding": "none" - } - ] - }, - { - "to_collection": "accounts", - "external_ids": [ - { - "id": "ghdctIwnA", - "type": "group_id", - "source_id": "DFAAJc2bE", - "collection": "accounts", - "created_at": "2018-10-07T06:22:47.406773Z", - "encoding": "none" - } - ] - } - ] - } - +```js +{ + "data": [ + { + "to_collection": "accounts", + "external_ids": [ + { + "id": "ADGCJE3Y8H", + "type": "group_id", + "source_id": "DFAAJc2bE", + "collection": "accounts", + "created_at": "2018-10-06T03:43:26.63387Z", + "encoding": "none" + } + ] + }, + { + "to_collection": "accounts", + "external_ids": [ + { + "id": "ghdctIwnA", + "type": "group_id", + "source_id": "DFAAJc2bE", + "collection": "accounts", + "created_at": "2018-10-07T06:22:47.406773Z", + "encoding": "none" + } + ] + } + ] +} +``` ## Personalization ### Recommended Implementation @@ -634,9 +657,11 @@ analytics.track('Subscription Upgraded', { }) ``` -*_NOTE_:* The `type` value should use snake_case notation; camelCase and special characters are not currently supported. +> note "" +> **Note:** The `type` value should use snake_case notation; camelCase and special characters are not currently supported. Now you can query the Profile API by subscription_id: - - https://profiles.segment.com/v1/spaces//collections/users/profiles/subscription_id:sub_1923923/traits +``` +https://profiles.segment.com/v1/spaces//collections/users/profiles/subscription_id:sub_1923923/traits +```