v.1.3

Profiles

Creates new profiles or updates existing ones if the profile_id already exists. The API supports various operations for flexible profile attribute manipulation.

‍Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
x-api-key	{your-api-key}	Yes

Request Body

The request body should contain an array of profile objects. Each profile object must include the required attributes and can contain any additional custom attributes as needed.

[
  {
    "app_id": "your_app_id",
    "profile_id": "user123",
    "urm_date_time": "2024-10-28T00:10:02.471Z",
    "urm_ip": "192.168.1.1",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_field1": "value1",
    "custom_field2": 42
  },
  {
    "app_id": "your_app_id",
    "profile_id": "user456",
    "urm_date_time": "2024-10-28T00:15:22.125Z",
    "urm_ip": "192.168.1.2",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "membership_level": "premium",
    "signup_date": "2024-10-15T14:30:00.000Z"
  }
]

Attributes

Attribute	Type	Required	Description
app_id	String	Yes	Unique identifier for your application provided by your Account Manager
profile_id	String	Yes	Unique identifier for the user profile
urm_date_time	Date String	Yes	ISO 8601 formatted timestamp of the profile creation/update
urm_insert_id	String	Yes	Unique identifier for the inserted record. If not provided, the system automatically generates a random value starting with "urm-"
urm_ip	String	No	IP address of the user

Custom Attributes

You can include any additional custom attributes in the profile object according to your business needs. These attributes can be of any supported data type (String, Number, Boolean, Date String, or Array).

Important Restriction: Custom attribute names must not start with "urm" (case-insensitive). Attribute names like "urm_custom", "URM_field", or "uRmData" will be rejected. The "urm_" prefix is reserved for system attributes.

System Directives

The /profiles API supports special system directives that allow for flexible profile attribute manipulation. These directives use the "urm_" prefix and enable operations beyond simple attribute creation or update.

Directive	Type	Description
urm_set	Object	Sets or updates the specified attributes with new values
urm_set_if_null	Object	Sets attributes only if they don't already exist (are null)
urm_unset	Array	Sets the specified attributes to null
urm_delete	Array	Completely removes the specified attributes from the profile
urm_add	Object	Adds (or subtracts) values to numeric attributes
urm_append	Object	Appends values to array attributes
urm_unique_append	Object	Appends values to array attributes only if they don't already exist
urm_remove	Object	Removes specified values from array attributes
urm_delete_profile	String	Deletes the entire profile (value should be "profile_id")
urm_merge	Array	Merges profiles listed in the array into the profile specified by profile_id

Directive Details and Usage

urm_set

Used to set or update specific attributes with new values. Pass an object containing key-value pairs where each key is the attribute name and each value is the new value to set.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:23:48.123Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-abc-123",
  "urm_set": {
    "first_name": "James",
    "last_name": "Doe",
    "age": 30,
    "is_active": true
  }
}

urm_set_if_null

Sets attributes only if they don't already exist or are null in the profile. This is useful for initialising attributes without overwriting existing values. Pass an object containing key-value pairs.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:24:12.456Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-def-456",
  "urm_set_if_null": {
    "first_name": "James",
    "signup_date": "2024-03-01T10:00:00.000Z",
    "default_language": "en",
    "welcome_email_sent": false
  }
}

urm_unset

Sets the specified attributes to null without removing them from the profile. Pass an array of attribute names to be nullified.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:25:33.789Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-ghi-789",
  "urm_unset": ["first_name", "last_login_date", "temporary_token"]
}

urm_delete

Completely removes the specified attributes from the profile. Unlike urm_unset, this directive removes the attributes entirely rather than setting them to null. Pass an array of attribute names to be deleted.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:26:45.321Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-jkl-012",
  "urm_delete": ["temporary_field", "old_attribute", "deprecated_setting"]
}

urm_add

Performs mathematical addition or subtraction on numeric attributes. Positive values increase the attribute value, negative values decrease it. Pass an object with attribute names as keys and numeric values to add/subtract.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:27:58.654Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-mno-345",
  "urm_add": {
    "login_count": 1,
    "credits": -10,
    "score": 25.5,
    "failed_attempts": 0
  }
}

urm_append

Adds new values to the end of array attributes. If the attribute doesn't exist, it creates a new array with the specified values. Pass an object where keys are attribute names and values are arrays containing items to append.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:29:17.987Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-pqr-678",
  "urm_append": {
    "tags": ["new_tag", "another_tag"],
    "visited_pages": ["/home", "/products"]
  }
}

urm_unique_append

Similar to urm_append, but only adds values if they don't already exist in the array (prevents duplicates). Pass an object where keys are attribute names and values are arrays containing items to append uniquely.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:30:22.123Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-stu-901",
  "urm_unique_append": {
    "device_ids": ["device_123"],
    "categories": ["premium", "active"],
    "urm_web_push_notification_token": ["token_xyz_123"]
  }
}

urm_remove

Removes specific values from array attributes. Pass an object where keys are attribute names and values are arrays containing items to remove from the corresponding arrays.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:31:45.456Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-vwx-234",
  "urm_remove": {
    "tags": ["old_tag", "deprecated_tag"],
    "device_tokens": ["expired_token_123"],
    "interests": ["no_longer_interested"]
  }
}

urm_delete_profile

Deletes the entire profile. The value must be the string "profile_id" to confirm deletion.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "user123",
  "urm_date_time": "2024-03-04T15:33:12.789Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-yz1-567",
  "urm_delete_profile": "profile_id"
}

urm_merge

Merges multiple profiles into the current profile. All attributes from the source profiles will be copied to the target profile, with the current profile's attributes taking precedence in case of conflicts. Pass an array of profile IDs from which to merge.

Complete Example:

{
  "app_id": "app1",
  "profile_id": "main_profile_id",
  "urm_date_time": "2024-03-04T15:34:33.321Z",
  "urm_ip": "192.168.1.1",
  "urm_insert_id": "operation-234-890",
  "urm_merge": ["old_profile_id1", "old_profile_id2", "duplicate_profile_id"]
}

‍

Code Snippet

curl -X POST "https://api.rapidpacecrm.com/profiles" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-key: your_api_key" \
  -d '[
    {
      "app_id": "your_app_id",
      "profile_id": "user123",
      "urm_date_time": "2024-10-28T00:10:02.471Z",
      "urm_ip": "192.168.1.1",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  ]'

Response

Success Response (200 OK)

{
  "EncryptionType": "KMS",
  "FailedRecordCount": 0,
  "Records": [
    {
      "SequenceNumber": "sequence_number_value",
      "ShardId": "shardId-ID"
    }
  ]
}

Error Response (400 Bad Request)

{
    "message": "Invalid request body"
}

Error Response (403 Forbidden)

{
    "message": "Forbidden"
}