Base Public API (1.0)

Update existing custom object records on advocates. Each batch item identifies the record by its instance ID (returned from a prior create) and supplies the attribute values to change. Items are processed independently — inspect per-record results in the response.

Use this for incremental sync of fields that change over time (e.g. subscription tier, renewal date).

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/advocate/custom-object-record/batch' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "users": [
      {
        "advocateEmail": "ada@example.com",
        "objects": [
          {
            "objectName": "subscription",
            "recordId": "sub-2026-001",
            "attributes": [
              { "attributeName": "plan", "values": ["Enterprise Plus"] }
            ]
          }
        ]
      }
    ]
  }'

Create one or more custom object records (and their attribute values) on advocates. Each item in the batch identifies a target advocate (by UUID or email) and a custom object apiName, then provides the attribute values to set.

Items are processed independently; per-record results — success UUID or error context — are returned in the response body. Use this for bulk-loading multi-row data like subscription history or meeting notes from your CRM.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/advocate/custom-object-record/batch' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "users": [
      {
        "advocateEmail": "ada@example.com",
        "objects": [
          {
            "objectName": "subscription",
            "recordId": "sub-2026-001",
            "attributes": [
              { "attributeName": "plan", "values": ["Enterprise"] },
              { "attributeName": "started_at", "values": ["2026-01-01"] }
            ]
          }
        ]
      }
    ]
  }'

Delete custom object records on advocates. Each batch item identifies the target advocate (advocateUuid or advocateEmail), the custom object (objectName), and a list of record ids (recordIds) to delete. Passing an empty recordIds array deletes every record of that object type on the advocate. Items are processed independently — per-record outcomes are returned.

Irreversible — the deleted records cannot be recovered.

Example:

curl -X DELETE 'https://prod.customershome.com/acauth/api/v1/advocate/custom-object-record/batch' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "users": [
      {
        "advocateEmail": "ada@example.com",
        "objectName":    "subscription",
        "recordIds":     ["sub-2026-001"]
      }
    ]
  }'

Update existing custom object records on accounts. Each batch item identifies the record by its instance ID (returned from a prior create) and supplies the attribute values to change. Items are processed independently — inspect per-record results in the response.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/account/custom-object-record/batch' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accounts": [
      {
        "accountName": "Analytical Engines Inc.",
        "objects": [
          {
            "objectName": "primary_contact",
            "recordId": "ext-pc-001",
            "attributes": [
              { "attributeName": "email", "values": ["ada.lovelace@example.com"] }
            ]
          }
        ]
      }
    ]
  }'

Create one or more custom object records (and their attribute values) on accounts. Each batch item identifies a target account (by UUID or name) and a custom object apiName, then provides the attribute values to set.

Items are processed independently — inspect per-record results in the response body.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/account/custom-object-record/batch' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accounts": [
      {
        "accountName": "Analytical Engines Inc.",
        "objects": [
          {
            "objectName": "primary_contact",
            "recordId": "ext-pc-001",
            "attributes": [
              { "attributeName": "full_name", "values": ["Ada Lovelace"] },
              { "attributeName": "email", "values": ["ada@example.com"] }
            ]
          }
        ]
      }
    ]
  }'

Delete custom object records on accounts. Each batch item identifies the target account (accountUuid or accountName), the custom object (objectName), and a list of record ids (recordIds) to delete. Passing an empty recordIds array deletes every record of that object type on the account. Items are processed independently — per-record outcomes are returned.

Irreversible — the deleted records cannot be recovered.

Example:

curl -X DELETE 'https://prod.customershome.com/acauth/api/v1/account/custom-object-record/batch' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accounts": [
      {
        "accountName": "Analytical Engines Inc.",
        "objectName":  "primary_contact",
        "recordIds":   ["ext-pc-001"]
      }
    ]
  }'

Read custom object records and their attribute values for one account. Identify the account by UUID or name (one of the two is required); identify the custom object by objectName (its apiName from the mapping).

Without instanceId, returns every record of that object type attached to the account. With instanceId, narrows the response to a single record. A common flow is: call the listing endpoint to discover instance IDs, then call this endpoint with one to read a specific record's attributes.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/account/custom-object-record/primary_contact?accountName=Analytical%20Engines%20Inc.' \
  -H 'Authorization: Bearer <jwt_token>'

Update a custom attribute. Both PUT and PATCH on this endpoint accept the same PatchCustomDataAttributeApiDTO body, and in both cases fields omitted (or sent as null) are left unchanged (booleans are boxed, so null does NOT mean false).

The two verbs differ only in the authority they require: PUT needs api.custom_attribute.add (the same scope used for Create), PATCH needs api.custom_attribute.update. New integrations should prefer PATCH so the token scope is narrow.

The attribute name, type, and owning entity cannot be changed once created — recreate the attribute under a new name if a different type is required.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/custom-attributes/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Favorite color",
    "description": "Updated description",
    "values": ["red", "green", "blue", "yellow"],
    "editableByAdvocate": true,
    "mandatory": false
  }'

Delete a custom attribute by UUID. The attribute is removed from every record that had a value for it; existing record values for this attribute are also deleted and cannot be recovered.

Returns 204 No Content on success. Use with care — there is no soft-delete.

Example:

curl -X DELETE 'https://prod.customershome.com/acauth/api/v1/custom-attributes/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <jwt_token>'

Partially update a custom attribute. Only fields present in the request are changed; omitted fields keep their current value (boolean toggles use Boolean so null means "leave unchanged", not "set to false").

Use this endpoint for everyday tweaks (label change, adding allowed picklist values, toggling visibility flags). The attribute name, type, and owning entity remain immutable.

Example:

curl -X PATCH 'https://prod.customershome.com/acauth/api/v1/custom-attributes/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{ "label": "Favourite colour" }'

List custom attributes defined for a given entity (contact = advocate, account, opportunity, nomination).

By default the response includes attributes inherited from a connected CRM in addition to Base-native attributes; pass includeCRM=false to see only the attributes you defined in Base. Use this to discover the schema before reading or writing attribute values on a specific record.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/custom-attributes?entity=contact&includeCRM=true' \
  -H 'Authorization: Bearer <jwt_token>'

Define a new custom attribute on an entity. The name becomes the API key used in all subsequent reads and writes — it must be unique per entity, all-lowercase, and only contain letters / digits / underscores. label is what admins and advocates see in the UI; you can change it later via PATCH.

For picklist attributes set type: "Enumerated" and supply the allowed values up front. To allow selecting multiple values from that list, also set multipleValues: true. For booleans use type: "Boolean" and leave values empty.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/custom-attributes' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "favorite_color",
    "label": "Favorite color",
    "description": "Advocate favorite color",
    "type": "Enumerated",
    "entity": "contact",
    "values": ["red", "green", "blue"],
    "editableByAdvocate": true
  }'

Retrieve nomination records that match the provided filter. Nominations are advocate-marketing requests created by salespeople or marketing — typically asking an advocate to participate in a case study, reference call, review, etc.

The filter requires a date range (dateFrom/dateTo) and accepts optional statuses, marketing admin UUIDs, salesperson names, specific nomination UUIDs, activity type names, and a free-text search. Set includeRepeatedNominations=true to surface advocates who were nominated more than once in the window. Use this for reporting / analytics dashboards.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/nomination' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "dateFrom": "2026-01-01",
    "dateTo": "2026-03-31",
    "statuses": ["IN_PROGRESS", "APPROVED"],
    "includeRepeatedNominations": false
  }'

Update an existing content category. Only present fields are changed — omit a field to leave it untouched.

Setting tagUuids replaces the full set of tags in this category (it is not an add-list). Tags removed from the set lose their category but are not deleted.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/content-categories/660e8400-e29b-41d4-a716-446655440111' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Updated description for technology",
    "tagUuids": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Delete an existing content category. Tags previously in this category are not deleted; they become uncategorized (you can re-assign them to another category via Update Content Tag).

Example:

curl -X DELETE 'https://prod.customershome.com/acauth/api/v1/content-categories/660e8400-e29b-41d4-a716-446655440111' \
  -H 'Authorization: Bearer <jwt_token>'

Update multiple content categories in a single request. The body is a map keyed by category UUID, so each entry follows the same semantics as the single-update endpoint (notably: tagUuids is a full replace, not a merge). Up to 100 entries per request.

Each entry is processed independently — inspect successful and failed in the response.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/content-categories/bulk' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "660e8400-e29b-41d4-a716-446655440111": {
      "description": "Updated tech description"
    },
    "660e8400-e29b-41d4-a716-446655440222": {
      "tagUuids": ["tag-uuid-5", "tag-uuid-6"]
    }
  }'

Create multiple content categories in a single request. Accepts 1 to 100 items; each item is processed independently. The response separates successful and failed items so a partial success is still a 201 — inspect the body.

Useful when migrating a content taxonomy from another system in one shot rather than looping on the single-create endpoint.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/content-categories/bulk' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '[
    { "name": "Technology", "description": "Tech content", "tagUuids": ["tag-uuid-1"] },
    { "name": "Marketing", "description": "Marketing content", "tagUuids": ["tag-uuid-2"] }
  ]'

Retrieve a paginated list of content categories with optional substring name filtering. Use the returned uuid of each category to scope a subsequent List Content Tags call to that category.

Maximum page size is 500; requests above that limit return 400.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/content-categories?name=tech&page=0&size=20' \
  -H 'Authorization: Bearer <jwt_token>'

Create a new content category and assign one or more existing tags to it. name must be unique within the company; tagUuids is required and must contain at least one tag.

If you need to create the tags first, call Create Content Tag (or its bulk variant) before this endpoint.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/content-categories' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Technology",
    "description": "All technology-related content",
    "tagUuids": ["550e8400-e29b-41d4-a716-446655440000", "550e8400-e29b-41d4-a716-446655440001"]
  }'

Update the description and/or category of an existing content tag. The tag name is immutable via this endpoint; create a new tag and delete the old one if you need to rename.

Pass tagCategoryUuid: null to move the tag back to top-level.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/content-tags/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Updated description",
    "tagCategoryUuid": "660e8400-e29b-41d4-a716-446655440222"
  }'

Delete an existing content tag. The tag is removed from every content item that referenced it; the content items themselves are not deleted. Deleting a tag that does not exist returns 404 — handle the not-found case explicitly if your sync runs may already have removed the tag.

Example:

curl -X DELETE 'https://prod.customershome.com/acauth/api/v1/content-tags/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <jwt_token>'

Update multiple content tags in a single request. The body is a map keyed by tag UUID, so the same description / tagCategoryUuid semantics as the single-update endpoint apply per entry. Up to 100 entries per request.

Each entry is processed independently — inspect successful and failed in the response to find out which entries committed. Useful for re-categorizing tags in bulk, e.g. moving all tags from a deprecated category to a new one.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/content-tags/bulk' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "550e8400-e29b-41d4-a716-446655440000": {
      "tagCategoryUuid": "660e8400-e29b-41d4-a716-446655440222"
    },
    "550e8400-e29b-41d4-a716-446655440001": {
      "description": "Updated description"
    }
  }'

Create multiple content tags in a single request. Accepts 1 to 100 items; each item is processed independently. The response contains a successful array of newly created UUIDs and a failed array with per-item error context (most commonly a DUPLICATE_NAME error when the tag already exists).

A partial failure (some items in failed) is still a 200 response — inspect the body to find out which items were created. Use this endpoint when seeding a new company or importing tags from a CRM rather than calling the single-create endpoint in a loop.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/content-tags/bulk' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '[
    { "name": "Product Launch", "tagCategoryUuid": "660e8400-e29b-41d4-a716-446655440111" },
    { "name": "Customer Success" }
  ]'

Retrieve a paginated list of content tags with optional filtering by name (substring match) and category UUID.

Typical flow: list categories first to obtain contentCategoryUuid, then list tags scoped to that category. Maximum page size is 500; requests above that limit return 400.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/content-tags?contentCategoryUuid=660e8400-e29b-41d4-a716-446655440111&page=0&size=50' \
  -H 'Authorization: Bearer <jwt_token>'

Create a new content tag.

name is required and must be unique within the company (case-insensitive). Pass a tagCategoryUuid to put the new tag under an existing category, or leave it null to create a top-level tag. The response body returns the new UUID; use it as the identifier for subsequent update or delete calls.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/content-tags' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product Launch",
    "description": "Used to mark content related to product launch campaigns",
    "tagCategoryUuid": "660e8400-e29b-41d4-a716-446655440111"
  }'

Get full data for a single user by external auth id (the identifier issued by the SSO provider — not the email and not the advocate UUID). Returns 404 if the user does not exist in the caller's company.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/users/auth0|abcd1234' \
  -H 'Authorization: Bearer <jwt_token>'

Update custom attribute values for an existing user identified by external SSO auth id. The payload mirrors Modify custom attributes for a single advocate — three optional maps for addCustomAttributes, updateCustomAttributes, and removeCustomAttributes. The endpoint does not change profile fields (name, email, jobTitle, company) directly; profile fields are managed via the registration / SSO flow.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/users/auth0|abcd1234' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateCustomAttributes": { "favorite_color": ["green"] },
    "removeCustomAttributes": ["deprecated_flag"]
  }'

Grant points (and optionally badges) to an advocate identified by email. Use a sensible reason string — it shows up in the advocate's points history and in admin audit logs.

Common use cases: bonus award, custom one-off recognition, retroactive correction after a missed activity. For automatic point-per-activity recognition, prefer wiring an activity type with a points reward and calling Trigger activity instead.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/points/grant-points' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "points": 250,
    "reason": "Spoke on the customer panel at SaaSCon 2026"
  }'

Get custom attribute values for one or more advocates. Pass a comma-separated list of advocate UUIDs as uuids; omit to return values for all advocates in the company (use with care on large tenants).

The response is a map keyed by advocate UUID; each value is an array of attribute readings. Combine with List custom attributes (entity=contact) to interpret what each attribute means.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/advocate/custom-attributes?uuids=550e8400-e29b-41d4-a716-446655440000,550e8400-e29b-41d4-a716-446655440001' \
  -H 'Authorization: Bearer <jwt_token>'

Update one or more custom attribute values on a single advocate identified by email. The request carries an array of {attributeName, values} rows — each row sets the values of one custom attribute (values is always an array; for single-value attributes pass a one-element array).

The response is an array of per-update result rows. Either attributeName or attributeUuid may be used to identify the attribute. Use the per-advocate-id variant (PUT /advocate/custom-attributes/{id}) when you already have the SSO auth id rather than the email.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/advocate/custom-attributes' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "attributes": [
      { "attributeName": "favorite_color", "values": ["blue"] },
      { "attributeName": "role", "values": ["VP Engineering"] }
    ]
  }'

Update custom attribute values for a single advocate identified by external auth id. The payload is partitioned into three maps so a single call can add, update, and remove attributes atomically:

• addCustomAttributes — { "<attributeName>": ["value1", "value2"] } — add the given values (no-op if the attribute already holds them).
• updateCustomAttributes — { "<attributeName>": ["value1", "value2"] } — replace the attribute's full value set with the supplied array.
• removeCustomAttributes — ["<attributeName>", ...] — remove the attribute entirely.

The response returns the resulting list of attribute values on the advocate. The companion PUT /advocate/custom-attributes endpoint targets the advocate by email + a flat [{attributeName, values}] array — use whichever identifier you already have on hand.

Example:

curl -X PUT 'https://prod.customershome.com/acauth/api/v1/advocate/custom-attributes/auth0|abcd1234' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateCustomAttributes": { "favorite_color": ["green"] }
  }'

List users (advocates) in the caller's company. Pass emails (comma-separated set) to look up specific advocates by email. Returns a basic projection — for full advocate data including custom attributes and consent, use List advocates instead.

Example:

curl -X GET 'https://prod.customershome.com/acauth/api/v1/users?emails=ada@example.com,alan@example.com&page=0&size=20' \
  -H 'Authorization: Bearer <jwt_token>'

Create a new advocate user in the caller's company. Email is unique per company — if the email already exists in this company the response is 400 with body EMAIL_CONFLICT.

The new user is created in an unactivated state; standard onboarding flows (invitation email, activation link) fire automatically. Use Import contacts by email for bulk onboarding instead of looping on this endpoint.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/users' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "jobTitle": "Chief Computing Officer"
  }'

Trigger a tracked activity for an advocate identified by email. The activity is recorded against the advocate and may award points, progress an open ASK, fire downstream automation, or all three depending on how the activity type is configured in admin.

Common patterns: a CRM sync calling this when an opportunity closes, a content platform calling it when an advocate posts a review, a webhook bridge translating third-party events into Base activities. Use List activity types to discover valid activity types beforehand.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/trigger-activity' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "apiIdentifier": "case_study_published"
  }'

Confirm that an advocate directed from the Base system completed registration. Call this from your registration landing page after the advocate's account is provisioned so Base can attribute the registration to the originating UTM campaign and capture profile fields submitted on the form.

utmCampaign is required and is the campaign id Base appended to the registration URL as ?utm_campaign=<id>. Other fields (firstName, lastName, jobTitle, tags, etc.) are optional and fall back to whatever was supplied earlier in the flow.

Example:

curl -X POST 'https://prod.customershome.com/acauth/api/v1/registration-confirmation' \
  -H 'Authorization: Bearer <jwt_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "utmCampaign": "spring-2026-launch",
    "step": 2,
    "utmSource": "linkedin",
    "tags": ["enterprise", "early-adopter"],
    "firstName": "Ada",
    "lastName": "Lovelace",
    "company": "Analytical Engines Inc.",
    "jobTitle": "Chief Computing Officer",
    "email": "ada@example.com"
  }'