Identities

Description

An identity resource represents an acting persona attached to customer profile, which can have activities created in CROWDMANAGER.

All identities are created in the scope of the ApiApp which is used for the authentication. Removing an ApiApp will result in losing the update/delete access to the identities created by that app, will recomand to refresh the api key rather than deleting an ApiApp.

Related topics

Fields

Name	Description	Type/Supported Values	Supported Methods
id	Id of the Identity	long	GET
externalId	Identity external id - unique among ApiApp	string	GET, POST
authenticationMethod	Identity Authentication Method	Enum {"none","email","phone","other"}	GET, POST
fullName	Identity full name	string	GET, POST, PUT
firstName	Identity first name	string	GET, POST, PUT
lastName	Identity last name	string	GET, POST, PUT
nickName	Identity nickname	string	GET, POST, PUT
gender	Identity gender	nullable Enum {"male","female","undefined"}	GET, POST, PUT
dateOfBirth	Identity date of birth.	nullable datetime	GET, POST, PUT
profileImageUrl	Identity profile image url	string	GET, POST, PUT
isAdult	Identity adult flag	nullable Enum {"false","true","unspecified"}	GET, POST, PUT
email	Identity email address	string	GET, POST, PUT
phone	Identity phone mumber	string	GET, POST, PUT
street	Identity address street	string	GET, POST, PUT
postalCode	Identity address postalCode	string	GET, POST, PUT
city	Identity address city	string	GET, POST, PUT
county	Identity address county	string	GET, POST, PUT
country	Identity address country	string	GET, POST, PUT
timeZone	Identity time zone. Should be an IANA timezone name id, specified in English (example: `Europe/Warsaw`)	string	GET, POST, PUT
extendedProperties	Customer Profile custom extended properties	JOBject	GET, POST, PUT
customAuthenticationFields	Customer Profile custom authentication fields*	JOBject	GET, POST, PUT
customerProfileId	Identity Customer Profile Id	long	GET

The CustomAuthenticationFields json's object key (key1, key2 in the example) is the ID defined in the Additional authentication fields on Campaigns Global settings page.

Requirements

The specified organization is required to have the ApiApp created and enabled.

Create Identity

Creates Identity.

Endpoint

POST https://api.crowdmanager.io/v2/{organization-id}/identities

ExternalId should be provided and is enforced to be unique per ApiApp, established by the Authorization token used in the request. AuthenticationMethod is immutable and can be set only in the POST request.

Example

Request

POST https://api.crowdmanager.io/v2/1201/identities
Authorization: Basic aaabbbccc111222333
Accept: application/json
Content-Type: application/json

Request body

{
    "externalId":"some string value",
    "authenticationMethod":"email",
    "fullName":"John Doe",
    "firstName":"John",
    "lastName":"Doe",
    "nickName":"John D",
    "gender":male,
    "dateOfBirth":"1987-12-21 08:15:00.000Z",
    "profileImageUrl":"https://image.service/image.png",
    "isAdult":"true",
    "email":john.doe@email.com,
    "phone":"tel:+47-979-72-123",
    "street":"2545 Golden Street",
    "postalCode":"33179",
    "city":"Miami",
    "county":FL,
    "country":"Florida",
    "timeZone":"US/Alaska",
    "extendedProperties" = {...}
    "customAuthenticationFields":{"key1":"val1","key2":"val2"},
}

Response

{
    "id":"1000",
    "externalId":"some string value",
    "authenticationMethod":"email",
    "fullName":"John Doe",
    "firstName":"John",
    "lastName":"Doe",
    "nickName":"John D",
    "gender":male,
    "dateOfBirth":"1987-12-21 08:15:00.000Z",
    "profileImageUrl":"https://image.service/image.png",
    "isAdult":"true",
    "email":john.doe@email.com,
    "phone":"tel:+47-979-72-123",
    "street":"2545 Golden Street",
    "postalCode":"33179",
    "city":"Miami",
    "county":FL,
    "country":"Florida",
    "timeZone":"US/Alaska",
    "extendedProperties" = {...}
    "customAuthenticationFields":{"key1":"val1","key2":"val2"},
    "customerProfileId":123,
}

Errors

Code	Error Message
400	"Provided ExternalId is invalid"
409	"There is already Identity: in scope of ApiApp System: "
409	"Not all CustomAuthenticationFields are valid. tenantId: "
409	"No valid email provided for Authentication Method "
409	"No valid phone provided for Authentication Method
409	"Authentication method not allowed: "
409	"Provided Timezone is an invalid IANA name id"

Update Identity

Updateable Identity fields: FullName, FirstName, LastName, NickName, Gender, DateOfBirth, ProfileImageUrl, IsAdult, Email, Phone, Street, PostalCode, City, County, Country, TimeZone. Updating "authentication method property" (email, phoneNumber) won't update credentials.

Endpoint

PUT https://api.crowdmanager.io/v2/{organization-id}/identities/{identityId}

Example

Request

PUT https://api.crowdmanager.io/v2/1201/identities/{identityId}
Authorization: Basic aaabbbccc111222333
Accept: application/json
Content-Type: application/json

Request body

{
    "fullName":"John Doe",
    "firstName":"John",
    "lastName":"Doe",
    "nickName":"John Updated",
    "gender":male,
    "dateOfBirth":"1987-12-21 08:15:00.000Z",
    "profileImageUrl":"https://image.service/image.png",
    "isAdult":"true",
    "email":john.doe@email.com,
    "phone":"tel:+47-979-72-123",
    "street":"2545 Golden Street",
    "postalCode":"33179",
    "city":"Miami",
    "county":FL,
    "country":"Florida",
    "timeZone":"US/Alaska",
    "extendedProperties" = {...}
    "customAuthenticationFields":{"key1":"val1","key2":"val2"},
}

Response

{
    "id":"1000",
    "externalId":"some string value",
    "authenticationMethod":"email",
    "fullName":"John Doe",
    "firstName":"John",
    "lastName":"Doe",
    "nickName":"John Updated",
    "gender":male,
    "dateOfBirth":"1987-12-21 08:15:00.000Z",
    "profileImageUrl":"https://image.service/image.png",
    "isAdult":"true",
    "email":john.doe@email.com,
    "phone":"tel:+47-979-72-123",
    "street":"2545 Golden Street",
    "postalCode":"33179",
    "city":"Miami",
    "county":FL,
    "country":"Florida",
    "timeZone":"US/Alaska",
    "extendedProperties" = {...}
    "customAuthenticationFields":{"key1":"val1","key2":"val2"},
    "customerProfileId":123,
}

Errors

Code	Error Message
400	"Provided ExternalId is invalid"
404	"Could not find Identity: in scope of ApiApp System: "
409	"Not all CustomAuthenticationFields are valid. tenantId: "
409	"Provided Timezone is an invalid IANA name id"

Get Identity

Get Identity by Id or ExternalId. Please note, that get by externalId will return Identity only created by particular ApiApp.

Endpoint

GET https://api.crowdmanager.io/v2/{organization-id}/identities/{identityId}
GET https://api.crowdmanager.io/v2/{organization-id}/identities?externalId={externalId}

Example

Request

GET https://api.crowdmanager.io/v2/1201/identities/{identityId}
Authorization: Basic aaabbbccc111222333
Accept: application/json

Response

{
    "id":"1000",
    "externalId":"some string value",
    "authenticationMethod":"email",
    "fullName":"John Doe",
    "firstName":"John",
    "lastName":"Doe",
    "nickName":"John D",
    "gender":male,
    "dateOfBirth":"1987-12-21 08:15:00.000Z",
    "profileImageUrl":"https://image.service/image.png",
    "isAdult":"true",
    "email":john.doe@email.com,
    "phone":"tel:+47-979-72-123",
    "street":"2545 Golden Street",
    "postalCode":"33179",
    "city":"Miami",
    "county":FL,
    "country":"Florida",
    "timeZone": "US/Alaska",
    "extendedProperties" = {...}
    "customAuthenticationFields":{"key1":"val1","key2":"val2"},
    "customerProfileId":123,
}

Errors

Code	Error Message
400	"Provided ExternalId is invalid"
404	"Could not find Identity: in scope of Tenant: "
404	"Could not find Identity: in scope of ApiApp System: "

Delete Identity

Delete Identity by Id. Please note that deletion is possible only for Identities created by the same ApiApp, established by the Authorization token used in request.

Endpoint

DELETE https://api.crowdmanager.io/v2/{organization-id}/identities/{identityId}

Example

Request

DELETE https://api.crowdmanager.io/v2/1201/identities/{identityId}
Authorization: Basic aaabbbccc111222333
Accept: application/json

Response

204 No Content

Errors

Code	Error Message
404	"Could not find Identity: in scope of ApiApp System: "
404	"Customer Profile with id was not found"