> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Profiles
> The central customer record in Omneo — everything links to a profile.
The Profiles API creates, reads, updates, and deletes customer profiles. A **Profile** is the central object in Omneo: transactions, incentives, identities, ratings, and lists all link to a profile. See [Profiles](/concepts/profiles/overview) for a full conceptual overview.
**Before adding a profile**, use the preflight endpoints to confirm the email or mobile is available. This avoids handling a `422 Unprocessable Entity` on every duplicate.
* [`POST /v3/profiles/availability`](/api-reference/profile/check-availability) checks whether an email or mobile is free to use.
* [`POST /v3/profiles/exists`](/api-reference/profile/check-profile-existence) returns the profile that owns a supplied email or mobile, if one exists.
**Add Profile (`POST /v3/profiles`) rejects duplicates.** If the supplied `email` or `mobile_phone` is already in use by an active (non-soft-deleted) profile, the request returns `422 Unprocessable Entity`. The profile is not created and no update is performed. An email previously held by a soft-deleted profile is treated as available.
**Edit Profile (`PUT /v3/profiles/{profile}`) has destructive-replace semantics on several nested collections.** Including `addresses`, `tags`, `statuses`, `regions`, or `organisations` in the body replaces the entire set on the profile, soft-deleting or detaching anything not in the supplied list. Omitting the key leaves the collection untouched. `identities`, `custom_attributes`, and `dates_attributes` are upserts and do not destroy unmatched entries. `comms_attributes` is a partial merge.
See [Mutation semantics on POST and PUT](/concepts/profiles/overview#mutation-semantics-on-post-and-put) for the complete table.
## What is a profile?
Profiles are the core of customer data within Omneo.
Use the Profiles API to quickly get access to core customer data such as name, gender, phone, birthday.
Or even attribute data such as hair colour or jacket size.
Profiles are one of the core features to the Omneo CX platform, and are used to link many other features of Omneo.
Use this API to Create, Read, Update and Delete customer Profiles.
## Profile Properties
```json theme={null}
{
"id":"92975ecb-5264-4d31-9f2b-789fa01f4555",
"external_id":null,
"title":"Mr",
"first_name":"Example",
"last_name":"User",
"full_name":"Example User",
"email":"exampleuser@omneo.io",
"gender":"male",
"currency":"AUD",
"joined_at":"2021-01-27 00:00:00",
"mobile_phone":"+61404123123",
"mobile_phone_country":61,
"mobile_phone_national":"404123123",
"mobile_phone_national_prefix":"0404123123",
"mobile_phone_e164":"+61404123123",
"secondary_phone":"+61421123123",
"birth_year":"1989",
"birth_month":"1",
"birth_day":"1",
"company":"Acme Shoe Co.",
"occupation":"Marketing",
"avatar_url":null,
"preferred_location_id":null,
"joined_location_id":null,
"joined_location":null,
"preferred_location":null,
"tier_handle":null,
"tier":null,
"birth_date":"1989-01-01",
"birth_days":339,
"birth_days_past":25,
"next_birthday":"2022-01-01",
"identities":[
],
"tags":[
],
"attributes":{
"comms":{
"profile_id":"92975ecb-5264-4d31-9f2b-789fa01f4555",
"email_optout":false,
"push_optout":false,
"sms_optout":false,
"phone_optout":false,
"post_optout":false,
"email_bounced":false,
"push_bounced":false,
"sms_bounced":false,
"phone_bounced":false,
"post_bounced":false,
"sms_promo":false,
"push_promo":true,
"email_promo":true,
"phone_promo":false,
"post_promo":false,
"email_discover":true,
"email_benefits":true,
"email_reminders":true,
"email_account":true,
"email_bookings":true,
"email_feedback":true,
"email_location":false,
"email_service":true,
"sms_discover":false,
"sms_benefits":false,
"sms_reminders":true,
"sms_account":false,
"sms_bookings":true,
"sms_feedback":false,
"sms_location":false,
"sms_service":true,
"push_discover":true,
"push_benefits":true,
"push_reminders":true,
"push_account":true,
"push_bookings":true,
"push_feedback":true,
"push_location":true,
"push_service":true,
"phone_discover":true,
"phone_benefits":true,
"phone_reminders":true,
"phone_account":true,
"phone_bookings":true,
"phone_feedback":true,
"phone_location":true,
"phone_service":true,
"post_discover":true,
"post_benefits":true,
"post_reminders":true,
"post_account":true,
"post_bookings":true,
"post_feedback":true,
"post_location":true,
"post_service":true,
"email_verification":"not_sent",
"sms_verification":"not_sent",
"phone_verification":"not_sent",
"post_verification":"not_sent",
"terms_accepted_at":null,
"terms_accepted_version":null,
"created_at":"2021-01-27 22:58:01",
"updated_at":"2021-01-27 22:58:01"
},
"appearance":{
"profile_id":"92975ecb-5264-4d31-9f2b-789fa01f4555",
"hair_colour":"Black",
"hair_length":"Short",
"shape_body":"Straight",
"shape_face":null,
"size_cup":null,
"size_hat":null,
"size_formal_jacket":null,
"size_formal_jacket_length":null,
"size_formal_shirt":null,
"size_formal_shirt_fit":null,
"size_formal_trouser":null,
"size_formal_trouser_drop":null,
"size_formal_trouser_leg":null,
"size_jacket":null,
"size_pant":null,
"size_shoe":null,
"size_type_age":null,
"size_type_region":null,
"size_top":null,
"skin_type":null,
"measurement_arm":null,
"measurement_arm_inside":null,
"measurement_bust":null,
"measurement_chest":null,
"measurement_foot_length":null,
"measurement_head":null,
"measurement_height":null,
"measurement_hip":null,
"measurement_leg_inside":null,
"measurement_leg_outside":null,
"measurement_neck":null,
"measurement_neck_to_wrist":null,
"measurement_shoulders":null,
"measurement_waist":null,
"measurement_weight":null,
"created_at":"2021-01-27 22:58:01",
"updated_at":"2021-01-27 22:58:01"
},
"dates": [
{
"id": 1,
"profile_id": "92a79bbb-76d1-4eec-ada9-92046381ffb6",
"date": "2020-05-13 00:00:00",
"is_recurring": true,
"recurring_schedule": "yearly",
"name": "date_name",
"handle": "date_handle",
"relationship": "wife",
"description": "anniversary",
"meta": [
"1"
],
"note": "note",
"created_at": "2021-02-05 00:41:39",
"updated_at": "2021-02-05 00:41:39"
}
]
},
"statuses":[
],
"custom_attributes":{
"custom":{
"example-field":"test"
}
},
"address":{
"id":9,
"address_line_1":"asd333",
"address_line_2":null,
"address_line_3":null,
"company":"Test Company",
"latitude":null,
"longitude":null,
"city":"Melbourne",
"postcode":"3002",
"state":"victoria",
"country":"Australia",
"notes":null,
"external_id":null,
"is_default":true,
"created_at":"2021-01-25 02:23:01",
"updated_at":"2021-01-26 23:17:57"
},
"addresses":[
{
"id":8,
"address_line_1":"123 Buckaby Lane",
"address_line_2":null,
"address_line_3":null,
"company":null,
"latitude":null,
"longitude":null,
"city":"Melbourne",
"postcode":"3002",
"state":"VIC",
"country":"Australia",
"notes":null,
"external_id":"12341234",
"is_default":true,
"created_at":"2021-01-25 02:10:47",
"updated_at":"2021-01-25 02:28:59"
},
{
"id":9,
"address_line_1":"321 Winston St",
"address_line_2":"Georgebury Crt Level 3",
"address_line_3":null,
"company":"Acme Shoe Co.",
"latitude":null,
"longitude":null,
"city":"Melbourne",
"postcode":"3002",
"state":"victoria",
"country":"Australia",
"notes":null,
"external_id":null,
"is_default":false,
"created_at":"2021-01-25 02:23:01",
"updated_at":"2021-01-26 23:17:57"
}
],
"created_at":"2021-01-27 22:58:01",
"updated_at":"2021-01-27 22:58:01",
"profile_type":"active"
}
```
| Attribute | Description |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id `READ-ONLY` `STRING` | The profile ID (UUID V4). |
| external\_id `STRING` `READ-ONLY` | The profile external ID. This field references the primary identities `identifier`. Denoted by the identity `is_primary` attribute. |
| title `STRING` | The profile salutation. |
| first\_name `STRING` | The profiles first name. |
| last\_name `STRING` | The profiles last name. |
| full\_name `STRING` `READ-ONLY` | The profiles full name. A concatenation of `first_name` and `last_name` |
| email `STRING` `EMAIL` | The profile email. This field must be unique, and cannot exist on another profile. |
| gender `STRING` | The profile gender. Accepted values are: \* `NULL` - Omit the gender field \* `female` \* `male` \* `withheld` \* `other` |
| currency `STRING` | The default currency attached to the profile *Must be configured as a valid currency in Omneo* |
| joined\_at `DATE-TIME` | The date the customer joined Omneo |
| mobile\_phone `STRING` `PHONE` | The primary mobile phone number with attached country code. example format: "+61412323123" This must be unique, and cannot exist on another profile |
| mobile\_phone\_country `INTEGER` `READ-ONLY` | The country code for the provided `mobile_phone` example: "61" |
| mobile\_phone\_national `STRING` `READ-ONLY` | The `mobile_phone` number without the country code. example: "412323123" |
| mobile\_phone\_national\_prefix `STRING` `READ-ONLY` | The `mobile_phone_national` with previx example: "0412323123" |
| mobile\_phone\_e164 `STRING` `READ-ONLY` | the E. 164 compliant `mobile_phone` number e.g "+61412323123" |
| secondary\_phone `STRING` | The secondary phone number for the profile. |
| birth\_year `INTEGER` | The year of birth example: Birthday: 1-5-1990 the `birth_year` is 1990 |
| birth\_month `INTEGER` | The month of birth Represented as a numeric value from (1-12) |
| birth\_day `INTEGER` | The day of birth |
| company `STRING` | The company of the profile |
| occupation `STRING` | the occupation of the profile |
| avatar\_url `STRING` `URL` | The image used as the profile avatar |
| preferred\_location\_id `INTEGER` | The profiles preferred location id Represented as the `id` of a valid [location](/api-reference/location/overview) configured in Omneo |
| preferred\_location\_external\_id `STRING` | An external reference for the profiles preferred location. This is usually the location reference as it sits in your primary system outside Omneo |
| joined\_location\_id `INTEGER` | The profiles joined location. Represented as the `id` of a valid [location](/api-reference/location/overview) configured in Omneo |
| joined\_location\_external\_id `STRING` | An external reference for the profiles joined location. This is usually the location reference as it sits in your primary system outside Omneo |
| joined\_location `INTEGER` `READ-ONLY` | `location` data for the specified `joined_location_id` |
| preferred\_location `INTEGER` | `location` data for the specified `preferred_location_id` |
| tier\_handle `STRING` `READ-ONLY` | The `tier_handle` of the profile Which displays the achieved `tier` the profile has reached. |
| tier `OBJECT` | Accompanying [tier](/api-reference/tier-definition) data for the profiles `tier_handle` |
| birth\_date `DATE` `READ-ONLY` | `YYYY-MM-DD` representation of `birth_year`, `birth_month` and `birth_day` |
| birth\_days `INTEGER` `READ-ONLY` | The count of days until the profiles next birthday. Calculated as the difference of days from this years `birth_date` until now. **If this years`birth_date` is in the past, then the following year will be used for the calculation** |
| birth\_days\_past `INTEGER` `READ-ONLY` | Value will return `null` if `birth_date` of this year, is in the future. If **this years** `birth_date` is in the past, `birth_days_past` will equal the number of days passed, since the profiles last birthday |
| next\_birthday `DATE` | The date of the profiles next birthday calculated 1 year from the profiles `birth_date` |
| identities `ARRAY` | The profiles attached identities\` |
| tags `ARRAY` | The profiles attached tags |
| attributes `ARRAY` | The profiles attached attributes |
| statuses `STRING` | An array of the profiles attached [Statuses](ref:statuses) Specify the status `handle` example: "influencer", "media", "staff" use [Browse Statuses](/api-reference/status/browse-statuses) to review available statuses. |
| custom\_attributes `ARRAY` | Custom attributes attached to the profile |
| address `STRING` | The default [address](/api-reference/profile-address) against the profile. |
| addresses `ARRAY` | All [addresses](/api-reference/profile-address) against the profile. |
| created\_at `DATE-TIME` `READ-ONLY` | The UTC date & time the Profile record was created in ISO 8601 format. |
| updated\_at `DATE-TIME` `READ-ONLY` | The UTC date & time the Profile record was last updated in ISO 8601 format. |
| profile\_type `STRING` | Accepted values: \* temporary \* pending \* active \* deleted |
# Event Context
*The profile context available in webhooks and targets.*
```json theme={null}
{
"id":"92975ecb-5264-4d31-9f2b-789fa01f4555",
"external_id":null,
"title":"Mr",
"first_name":"Example",
"last_name":"User",
"full_name":"Example User",
"email":"exampleuser@omneo.io",
"gender":"male",
"currency":"AUD",
"joined_at":"2021-01-27 00:00:00",
"mobile_phone":"+61404123123",
"mobile_phone_country":61,
"mobile_phone_national":"404123123",
"mobile_phone_national_prefix":"0404123123",
"mobile_phone_e164":"+61404123123",
"secondary_phone":"+61421123123",
"birth_year":"1989",
"birth_month":"1",
"birth_day":"1",
"company":"Acme Shoe Co.",
"occupation":"Marketing",
"avatar_url":null,
"preferred_location_id":null,
"joined_location_id":null,
"joined_location":null,
"preferred_location":null,
"tier_handle":null,
"tier":null,
"birth_date":"1989-01-01",
"birth_days":339,
"birth_days_past":25,
"next_birthday":"2022-01-01",
"tier_handle" : "tier_handle",
"reward_balance" : 131,
"point_balance" : 100,
"combined_balance_dollars" : 231,
"aggregations" : {}, // Aggregation Context
"is_completed" : true,
"tier" : {}, // Tier Context
"identities":[], // Identities Context
"tags":[
{
"created_at" : "2021-04-23 02:04:38",
"handle" : "tag1",
"id" : 11,
"updated_at" "2021-04-23 02:04:38"
},
{
"created_at" : "2021-04-23 02:04:38",
"handle" : "tag2",
"id" : 12,
"updated_at" "2021-04-23 02:04:38"
}
],
"flattened_tags" : ['tag1', 'tag2'],
"flattened_statuses" : ['status1', 'status2'],
"attributes":{
"comms":{}, // Comms Context
"appearance":{}, // Appearence Context
"dates": [] // Dates Context
},
"statuses":[
{
"created_at" : "2021-04-23 02:04:38",
"handle" : "status1",
"id" : 110,
"updated_at" "2021-04-23 02:04:38"
},
{
"created_at" : "2021-04-23 02:04:38",
"handle" : "status2",
"id" : 111,
"updated_at" "2021-04-23 02:04:38"
}
],
"custom_attributes":{
"custom":{
"example-field":"test"
}
},
"address":{}, //Address Context
"addresses":[], // Addresses Context
"created_at":"2021-01-27 22:58:01",
"updated_at":"2021-01-27 22:58:01",
"profile_type":"active"
}
```