Attributes

This guide explains how to manage contact attributes using our unified API endpoint. With this endpoint you can add new attributes, update existing ones, or remove attributes (by setting them to null) for one or more contacts. This streamlined approach minimizes unnecessary data processing by sending only the changed values (deltas).

Table of Contents

• Overview
• Endpoint Details
• Request Format
• Response Format
• Error Handling
• Examples
• Best Practices
• Conclusion

Overview

The Aampe API provides a single, unified endpoint to manage contact attributes for audience creation. This endpoint allows you to:

• Add Attributes: Introduce new data points to a contact profile.
• Update Attributes: Modify existing values.
• Remove Attributes: Delete attributes by setting them to null.

This design is efficient because you send only the changes (deltas), reducing data point consumption and ensuring your contact data remains up to date.

Endpoint Details

URL:

POST https://api.aampe.com/v1/contacts/attributes

Request Format

The request body must be a JSON object with a single key, contacts, which is an array of update objects. Each update object must include:

• contact_id: A unique identifier for the contact.
• attributes: An object containing key-value pairs for the attributes.
  • To remove an attribute, set its value to null.
  • To add or update an attribute, set its value to the desired value.
• timestamp (optional): An ISO 8601 formatted timestamp indicating when the update occurred.

Example Request Body

{
  "contacts": [
    {
      "contact_id": "contact123",
      "attributes": {
        "age": 30,
        "premium_member": true,
        "location": null
      },
      "timestamp": "2025-02-26T15:30:00Z"
    },
    {
      "contact_id": "contact456",
      "attributes": {
        "premium_member": true
      }
    }
  ]
}

In this example:

• contact123:

  • The age attribute is set to 30.
  • The premium_member attribute is set to true.
  • The location attribute is removed (value is null).

• contact456:

  • The premium_member attribute is set to true.

Response Format

A successful response returns a JSON object with the following keys:

• success: A boolean flag indicating that the request was processed.
• results: An array with the updated attributes for each contact. Attributes that were removed (set to null) will not appear in the returned data.

Example Response

{
  "success": true,
  "results": [
    {
      "contact_id": "contact123",
      "attributes": {
        "age": 30,
        "premium_member": true
      }
    },
    {
      "contact_id": "contact456",
      "attributes": {
        "premium_member": true
      }
    }
  ]
}

Error Handling

The API may return several HTTP status codes based on the outcome of the request:

• 200 OK: The update was successful.
• 400 Bad Request: The JSON payload is invalid or required fields are missing.
• 401 Unauthorized: Authentication is missing or invalid.
• 404 Not Found: One or more specified contacts do not exist.

Error responses include a JSON object with an error message that describes the issue.

Example Error Response

{
  "error": "Invalid contact_id: contact999"
}

Best Practices

• Send Only Deltas:
  Include only the attributes that have changed since the last update to minimize data processing and bandwidth usage.

• Include Timestamps (Optional):
  Use the timestamp field to help maintain the correct order of updates and assist with debugging.

• Secure Your API Token:
  Always keep your API token confidential and use HTTPS to protect your data in transit.

• Use Consistent Data Formats:
  Ensure that attribute values are consistently formatted (e.g., booleans as true/false, numbers as numeric types).