Customers

Register the person or business that will pay your Raims account as a customer. Their CPF or CNPJ identifies them; you can also provide a name, contact details and address.

Customers belong to the company and environment of the key used in the request. Sandbox and Production records are kept separate.

The base URL for requests is https://api.raims.com.

Phone number and dialing code are optional. You can provide either one without the other. The API does not check whether the number follows the country's telephone numbering rules. Registering a phone number does not confirm that it is active or belongs to the customer.

Create a customer

Create a customer, with POST /v1/customers, accepts the customer data and returns an identifier with the cus_ prefix. Store this identifier in your system to recognize the registered customer.

CPF or CNPJ is required. Name, contact details and address are optional. A tax ID already registered in the same company and environment updates the existing customer and keeps their identifier. If the request ends without a conclusive response, check the customer before repeating the request.

Validate the CPF or CNPJ in your integration's form and server before sending the customer data. The CPF and CNPJ validation guide explains check digits, alphanumeric CNPJ and how to handle INVALID_TAXID so the user can correct the field.

When you provide only zip_code for the address, Raims can fill in the street, neighborhood, city and state using the available postal code data. Any value in the street, neighborhood, city, state, number or address complement prevents automatic completion. In that case, send the address data you want to register. Empty fields or fields containing only spaces do not prevent postal code completion. If the postal code is not found, the customer can still be registered.

Reference in your system

Send the customer's identifier in your system as external_reference. The reference appears in lookups and can be changed or removed without changing the Raims ID. Omitting this field keeps the current reference, both when registering the same CPF/CNPJ again and when updating by ID.

To find the customer by your system's code, provide external_reference in the customer list. The search compares the full value and is case-sensitive and accent-sensitive. For example, ERP-123 does not match erp-123 or values that only contain 123. Different customers can share the same reference; also use the returned id to identify each record.

Additional integration data

Use metadata to associate small pieces of information from your system with the customer, such as a branch code or registration channel. Send an object with text key names and values:

{
  "metadata": {
    "filial": "SP-01",
    "canal": "loja"
  }
}

The map accepts up to 32 keys. Names use unaccented letters, numbers, periods, hyphens or underscores and are case-sensitive. Size limits also apply to the resulting map after an update, including existing keys. Do not use this field for passwords, tokens, personal documents or other sensitive data.

If metadata is not provided when creating a customer, the map is empty. When registering an existing CPF/CNPJ again or updating by ID, the keys you send are added or replaced; other keys are kept. Omitting metadata or sending {} keeps the map. Send null as a key's value to remove it, or metadata: null to remove all keys. An empty string is a valid value and does not remove the key.

Create, update and lookup responses return metadata, with {} when there are no values. This data cannot be used as search filters and is not automatically included in webhook bodies.

List customers

List customers, with GET /v1/customers, looks up customers in the company and environment of the key. You can filter by identifier, name, email, CPF/CNPJ or external reference and receive up to 100 customers per page. Without page_size, the page contains up to 10 customers.

Send filters in the URL, without a JSON body. Leave filters you do not want to use empty.

The response contains list and page. Start without a cursor and process the customers in list. While page.has_next is true, copy page.next_after to after in the next request, keeping the filters. Copy the full value without interpreting or calculating its contents.

The Listing and pagination guide also explains how to go back with before. Send only one cursor per request; do not fill in both after and before. A cursor that is empty or contains only spaces is not used in the query.

The newest customers appear first, including in name searches. To search by name, provide at least two characters, excluding leading and trailing spaces. A filter that is empty or contains only spaces does not restrict the search.

The external reference search can be combined with other filters. New records or changes may take a few seconds to appear in this search. Avoid continuous requests at short intervals. Keep the reference and other filters when continuing pagination.

Retrieve a customer

If you already have the identifier with the cus_ prefix, use Retrieve a customer, with GET /v1/customers/{id}, to look up their data. Use the id returned by the API without changes in the URL path. The request does not accept a JSON body.

This lookup lets you check the customer without going through the list. The customer must belong to the company and environment of the key. If they are not available to that key, check the identifier and credential used.

Update an existing customer

Use Update an existing customer when you already have the id and need to change the name, contact details, address or additional integration data, with PATCH /v1/customers/{id}. Provide the identifier in the path and send only the fields you want to change. Omitted fields keep their current value. For optional text fields, sending null or an empty value clears the field. The metadata map follows the update by key rules.

The identifier and CPF or CNPJ stay the same. This request does not create customers and requires a record from the same company and environment as the key. You can change the phone fields separately. Changing zip_code does not automatically fill in the other address fields.

Delete a customer

Use Delete a customer when you no longer need the record, with DELETE /v1/customers/{id}. Provide the id returned by the API in the path. The request has no body; the customer must belong to the company and environment of the key.

A customer can only be deleted when they have no linked charges that have not been deleted, including paid charges. Otherwise, the customer is kept. Deleting a customer does not delete charges or refund payments.

If you receive CUSTOMER_HAS_CHARGES, use GET /v1/charges with the customer_id filter to identify the linked charges. The endpoint reference is in List charges. Paid or canceled charges also prevent deletion while they remain in the records. Revoking a charge does not remove that link.

The customer no longer appears in the list or in lookups by ID. Repeating the request for a customer already deleted from the same company and environment returns the same confirmation.

Delete customers in bulk

Delete customers in bulk uses DELETE /v1/customers and accepts 1 to 100 IDs in the identifiers array of the JSON body. Results are separated into removed, blocked and invalid. Customers with charges that have not been deleted, including paid charges, are kept. Check each group to see which customers were deleted. The errors array identifies the position of each item with an issue and explains the reason. For example, identifiers[2] corresponds to the third item in the request. Use this information to correct the items that were not deleted.

See each endpoint page for fields, code examples and API responses. To prepare your integration credential, see API keys.