Skip to main content
Browse docs

Customers API

13 endpoints — authenticate with a workspace access token via Authorization: Bearer. See the API introduction for base URLs, pagination, and rate limits.

List Customers

GET/api/customers/

List customers. **Scopes**: `customers:read` `customers:write`

Query parameters

workspace_idstring | string[] | null

Filter by workspace ID.

emailstring | null

Filter by exact email.

querystring | null

Filter by name, email, or external ID.

pageinteger

Page number, defaults to 1.

limitinteger

Size of a page, defaults to 10. Maximum is 100.

sorting"email" | "-email" | "name" | "-name" | "created_at" | "-created_at"[] | null

Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order.

metadataobject | null

Filter by metadata key-value pairs using ``deepObject`` style, e.g. ``?metadata[key]=value``.

Returns 200 with PaginatedList_CustomerWithMembers_.

curl -X GET \
  https://api.rapidly.tech/api/customers/ \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Create Customer

POST/api/customers/

Create a customer. **Scopes**: `customers:write`

Request body CustomerCreate

metadataobject

Custom key-value attributes. Keys: string, max **40** chars. Values: string (max **500** chars), integer, float, or boolean. Limit: **50** pairs.

external_idstring | null

The ID of the customer in your system. This must be unique within the workspace. Once set, it can't be updated.

emailstringrequired

The email address of the customer. This must be unique within the workspace.

namestring | null

Name

billing_addressAddressInput | null
type"individual" | "team" | null

The type of customer. Defaults to 'individual'. Set to 'team' for customers that can have multiple members.

workspace_idstring | null

The ID of the workspace owning the customer. **Required unless you use an workspace token.**

ownerOwnerCreate | null

Optional owner member to create with the customer. If not provided, an owner member will be automatically created using the customer's email and name.

Returns 201 with CustomerWithMembers.

curl -X POST \
  https://api.rapidly.tech/api/customers/ \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Export Customers

GET/api/customers/export

Export customers as a CSV file. **Scopes**: `customers:read` `customers:write`

Query parameters

workspace_idstring | string[] | null

Filter by workspace ID.

Returns 200 with object.

curl -X GET \
  https://api.rapidly.tech/api/customers/export \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Get Customer

GET/api/customers/{id}

Get a customer by ID. **Scopes**: `customers:read` `customers:write`

Path parameters

idstringrequired

The customer ID.

Returns 200 with CustomerWithMembers.

curl -X GET \
  https://api.rapidly.tech/api/customers/{id} \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Update Customer

PATCH/api/customers/{id}

Update a customer. **Scopes**: `customers:write`

Path parameters

idstringrequired

The customer ID.

Request body CustomerUpdate

metadataobject

Custom key-value attributes. Keys: string, max **40** chars. Values: string (max **500** chars), integer, float, or boolean. Limit: **50** pairs.

emailstring | null

The email address of the customer. This must be unique within the workspace.

namestring | null

Name

billing_addressAddressInput | null
external_idstring | null

The ID of the customer in your system. This must be unique within the workspace. Once set, it can't be updated.

type"individual" | "team" | null

The customer type. Can only be upgraded from 'individual' to 'team', never downgraded.

Returns 200 with CustomerWithMembers.

curl -X PATCH \
  https://api.rapidly.tech/api/customers/{id} \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete Customer

DELETE/api/customers/{id}

Delete a customer. This action cannot be undone and will immediately: - Soft-delete the customer record - Clear any `external_id` Set `anonymize=true` to also anonymize PII for GDPR compliance. **Scopes**: `customers:write`

Path parameters

idstringrequired

The customer ID.

Query parameters

anonymizeboolean

If true, also anonymize the customer's personal data for GDPR compliance. This replaces email with a hashed version, hashes name and billing name, clears billing address, and removes OAuth account data.

Returns 204 with unknown.

curl -X DELETE \
  https://api.rapidly.tech/api/customers/{id} \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Get Customer by External ID

GET/api/customers/external/{external_id}

Get a customer by external ID. **Scopes**: `customers:read` `customers:write`

Path parameters

external_idstringrequired

The customer external ID.

Returns 200 with CustomerWithMembers.

curl -X GET \
  https://api.rapidly.tech/api/customers/external/{external_id} \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Update Customer by External ID

PATCH/api/customers/external/{external_id}

Update a customer by external ID. **Scopes**: `customers:write`

Path parameters

external_idstringrequired

The customer external ID.

Request body CustomerUpdateExternalID

metadataobject

Custom key-value attributes. Keys: string, max **40** chars. Values: string (max **500** chars), integer, float, or boolean. Limit: **50** pairs.

emailstring | null

The email address of the customer. This must be unique within the workspace.

namestring | null

Name

billing_addressAddressInput | null

Returns 200 with CustomerWithMembers.

curl -X PATCH \
  https://api.rapidly.tech/api/customers/external/{external_id} \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete Customer by External ID

DELETE/api/customers/external/{external_id}

Delete a customer by external ID. Soft-deletes the customer record. Set `anonymize=true` to also anonymize PII for GDPR compliance. **Scopes**: `customers:write`

Path parameters

external_idstringrequired

The customer external ID.

Query parameters

anonymizeboolean

If true, also anonymize the customer's personal data for GDPR compliance.

Returns 204 with unknown.

curl -X DELETE \
  https://api.rapidly.tech/api/customers/external/{external_id} \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Get Customer State

GET/api/customers/{id}/state

Get a customer state by ID. The customer state includes information about the customer's active meters. It's the ideal endpoint to use when you need to get a full overview of a customer's status. **Scopes**: `customers:read` `customers:write`

Path parameters

idstringrequired

The customer ID.

Returns 200 with CustomerState.

curl -X GET \
  https://api.rapidly.tech/api/customers/{id}/state \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Get Customer State by External ID

GET/api/customers/external/{external_id}/state

Get a customer state by external ID. The customer state includes information about the customer's active meters. It's the ideal endpoint to use when you need to get a full overview of a customer's status. **Scopes**: `customers:read` `customers:write`

Path parameters

external_idstringrequired

The customer external ID.

Returns 200 with CustomerState.

curl -X GET \
  https://api.rapidly.tech/api/customers/external/{external_id}/state \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Get Customer

GET/api/customer-portal/customers/me

Get authenticated customer. **Scopes**: `customer_portal:read` `customer_portal:write`

Returns 200 with CustomerPortalCustomer.

curl -X GET \
  https://api.rapidly.tech/api/customer-portal/customers/me \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN"

Update Customer

PATCH/api/customer-portal/customers/me

Update authenticated customer.

Request body CustomerPortalCustomerUpdate

billing_namestring | null

Billing Name

billing_addressAddressInput | null

Returns 200 with CustomerPortalCustomer.

curl -X PATCH \
  https://api.rapidly.tech/api/customer-portal/customers/me \
  -H "Authorization: Bearer $RAPIDLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'