{"openapi":"3.0.0","info":{"title":"People API","description":"Manages people (contact) records within Dotdigital Personalization. People records store identity and behavioural attributes used to drive personalised experiences. Operations include listing and searching people, retrieving a specific person's profile, updating person attributes, and deleting person records.","version":"1.0.1"},"servers":[{"url":"https://{region}-api-freshrelevance.dotdigital.com/api","variables":{"region":{"description":"The region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"apiTokenAuth":[]}],"paths":{"/{website_id}/people/":{"get":{"tags":["Manage people"],"summary":"List people","description":"Retrieves a list of people.","operationId":"getListPeople","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1}],"responses":{"200":{"description":"The page of people data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"},"examples":{"success":{"value":{"links":{"next":"https://api.freshrelevance.com/api/abc1234/people/?format=json&limit=2&page=2"},"count":22862,"total":22862,"page":1,"results":[{"details":"https://api.freshrelevance.com/api/abc1234/people/67504952eb52d7121aa01135/?format=json","email":"joe.bloggs@emailsim.io","did":"joe_dot_blogss_emailsim_dot_io_CS","_id":"67504952eb52d7121aa01135","loyalty":{},"extend":"{}"},{"details":"https://api.freshrelevance.com/api/abc1234/people/675027229e1601989c39ccb5/?format=json","did":"wsvz7pq5aw","dt":"2024-12-04 09:55:45","_id":"675027229e1601989c39ccb5","loyalty":{},"extend":"{}","perm":true}]}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/people/search/{search_type}/{search_value}/":{"get":{"tags":["Manage people"],"summary":"Search people","description":"Searches the list of people based on your criteria and returns their people ids if found.","operationId":"getSearchPeople","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"search_type","in":"path","description":"The key to search on, one of:\n* **email** - Email address\n* **did** - Device id\n* **sid** - Session id\n* **eid** - External id\n* **cid** - Customer id\n* **pid** - Dotdigital Personalization person id","required":true,"schema":{"type":"string","enum":["email","did","sid","eid","cid","pid"]}},{"name":"search_value","in":"path","description":"The value to search for inaccordance with your search type.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_1"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/people/{person_id}/":{"get":{"tags":["Manage people"],"summary":"Get person","description":"Retrieves a persons details.","operationId":"getGetPerson","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"person_id","in":"path","description":"The Dotdigital Personalization person id to retrieve.","required":true,"schema":{"type":"string","example":"67114952eb52d7121aa01135"}}],"responses":{"200":{"description":"The page of people data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"put":{"tags":["Manage people"],"summary":"Update person","description":"Updates a persons details.","operationId":"putUpdatePerson","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"person_id","in":"path","description":"The Dotdigital Personalization person id to update.","required":true,"schema":{"type":"string","example":"67114952eb52d7121aa01135"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonRequest"}}}},"responses":{"200":{"description":"Update successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_2"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"delete":{"tags":["Manage people"],"summary":"Delete person","description":"Deletes a person.","operationId":"delDeletePerson","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"person_id","in":"path","description":"The Dotdigital Personalization person id to delete.","required":true,"schema":{"type":"string","example":"67114952eb52d7121aa01135"}}],"responses":{"200":{"description":"Update successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_2"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}}},"components":{"schemas":{"Person":{"required":["_id","details","did","do_not_process","dt","eid","email","email_exclusion","extend","fn","ln","loyalty","perm","redirect_to"],"type":"object","properties":{"_id":{"type":"string","description":"Unique id for the person.","example":"681e4833e847a804846e7b9b"},"email":{"type":"string","description":"Email address","format":"email","example":"joe.bloggs@emailsim.io"},"did":{"type":"string","description":"Device identifier.","nullable":true,"example":"1tootoq9kn"},"eid":{"type":"string","description":"External identifier.","nullable":true,"example":"12345"},"dt":{"type":"string","description":"Date last modified in ISO-8601 format.","format":"date-time"},"fn":{"type":"string","description":"First name","nullable":true,"example":"Joe"},"ln":{"type":"string","description":"Last name","nullable":true,"example":"Bloggs"},"details":{"type":"string","description":"A URL to access the persons details.","format":"uri","example":"https://api.freshrelevance.com/api/abc12345/people/67504452eb52d7121aa01135/?format=json"},"extend":{"type":"string","description":"Extension properties as a JSON string.","format":"json","nullable":true,"example":"{ \"favorite_color\": \"red\" }"},"loyalty":{"type":"object","description":"Loyalty properties."},"redirect_to":{"type":"string","description":"The page to redirect to after an unsubscribe.","format":"uri","nullable":true},"do_not_process":{"type":"boolean","description":"Indicate that the person should not have their data processed.","nullable":true},"perm":{"type":"boolean","description":"Permission to market via email.","nullable":true},"email_exclusion":{"type":"boolean","description":"Indicate that the person should not recieve emails.","nullable":true}},"additionalProperties":false},"PersonRequest":{"type":"object","properties":{"email":{"type":"string","description":"Email address","format":"email","example":"joe.bloggs@emailsim.io"},"eid":{"type":"string","description":"External identifier.","nullable":true,"example":"12345"},"do_not_process":{"type":"boolean","description":"Indicate that the person should not have their data processed.","nullable":true},"explicitPermission":{"type":"boolean","description":"Permission to market via email.","nullable":true},"email_exclusion":{"type":"boolean","description":"Indicate that the person should not recieve emails.","nullable":true}},"additionalProperties":{"type":"string","description":"You can add additonal fields using the fields naming conventions of:\n* **extend.**_{Your field name}_ - Add extension data to person\n* **content.**_{Your field name}_ - Add content data to person"},"example":{"eid":1234,"explicitPermission":true,"extend.favourite_colour":"red","content.greeting":"Hey,"}},"PaginatedData":{"required":["count","links","page","total"],"type":"object","properties":{"page":{"minimum":1,"type":"integer","description":"The index for the page of data returned.","example":1},"count":{"minimum":0,"type":"integer","description":"Number of records in the page.","example":12},"total":{"minimum":0,"type":"integer","description":"Total number of records in the set.","example":12},"links":{"$ref":"#/components/schemas/PaginatedData_links"}},"description":"Data page and pagination links"},"inline_response_200":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["results"],"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Person"}}},"description":"The people details."}]},"inline_response_200_1":{"required":["results"],"type":"object","properties":{"total":{"type":"integer","description":"Total people found matching your search criteria.","example":1},"results":{"type":"array","description":"The details of the people that were found.","items":{"$ref":"#/components/schemas/inline_response_200_1_results"}}}},"inline_response_200_2":{"required":["ok"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates whether the call succeeded.","enum":[true]}}},"PaginatedData_links":{"type":"object","properties":{"next":{"type":"string","description":"URL of the next page.","format":"url","nullable":true},"previous":{"type":"string","description":"URL of the previous page.","format":"url","nullable":true}},"description":"Page navigation links"},"inline_response_200_1_results":{"required":["person_id"],"type":"object","properties":{"person_id":{"type":"string","description":"The Dotdigital Personalization unique person id.","example":"67114952eb52d7121aa01135"}}}},"responses":{"ErrorResponse":{"description":"An error occurred","content":{"application/json":{"schema":{"required":["error","ok"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates the call failed","enum":[false]},"error":{"oneOf":[{"type":"string","description":"The reason the call errored","example":"Validation error. No folder bd8eciompb7y, unable to delete"},{"type":"object","additionalProperties":{"minItems":1,"type":"array","items":{"type":"string","example":"This field may not be null."}},"description":"Fields with issues and their errors"}]}}}}}},"403Response":{"description":"Forbidden - Usually you are requesting data for a website you don't have access to."}},"parameters":{"WebsiteId":{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},"FormatJson":{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},"Limit":{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},"Page":{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1}},"securitySchemes":{"apiTokenAuth":{"type":"apiKey","name":"x-api-key","in":"header"}}},"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"]}