Customers

Create, retrieve, list and delete the individuals and businesses you make transfers for.

A Customer is an individual or a business you make transfers for. Create a Customer first, then onboard them before they can transact.

ActionEndpoint
Create a customerPOST /api/v1/customers
Retrieve a customerGET /api/v1/customers/{customer_uuid}
List all customersGET /api/v1/customers
Delete a customerDELETE /api/v1/customers/{customer_uuid}
Get an agreement linkPOST /api/v1/customers/{customer_uuid}/agreement_link

Create a Customer

POST /api/v1/customers

Required fields:

  • Individual: type, first_name, last_name, email, birth_date
  • Business: type, company_name, email
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/customers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
  "type": "individual",
  "first_name": "{{FIRST_NAME}}",
  "last_name": "{{LAST_NAME}}",
  "email": "{{EMAIL}}",
  "phone_country_code": "{{PHONE_COUNTRY_CODE}}",
  "phone_number": "{{PHONE_NUMBER}}",
  "birth_date": "{{BIRTH_DATE}}",
  "description": "{{DESCRIPTION}}"
}'
{
    "data": {
        "uuid": "cus_8mlcKk9cN9HjogohJnYHW0dwD6pmFlZnuowUPjLh",
        "object": "customer",
        "status": "unfinished",
        "state": "not_started",
        "type": "individual",
        "first_name": "John",
        "middle_name": null,
        "last_name": "Morgan",
        "email": "[email protected]",
        "phone_country_code": "US",
        "phone_number": "555-555-1234",
        "birth_date": "1988-04-15",
        "is_bank_account_linkable": false,
        "is_card_linkable": false,
        "description": "Sample individual customer for the docs.",
        "intermediary_fi_reference": null,
        "created_at": "2026-10-05T04:55:32+00:00",
        "updated_at": "2026-10-05T04:55:32+00:00",
        "has_signed_agreement": false,
        "agreement_link": "https://harbor-sandbox.owlpay.com/agreements?uuid=agt_vLH2kDK7a4NnktmcXa3bSEeVKkIMNRp1IFJo1bEu",
        "verification_link": "https://harbor-sandbox.owlpay.com/gokyc?expires=1791176732&hash=f6dc4877bf7da7dc33874de39e49ff97e6485dd6dd0bdb221635de9b25143567",
        "rfi_link": null
    }
}
  • Save the uuid. You need it for every other Customer request.
  • A new Customer starts with status: unfinished. Send them the agreement_link and verification_link to start onboarding.

Retrieve a Customer

GET /api/v1/customers/{customer_uuid}

Returns one Customer. The response has the same fields as Create a Customer.

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'

List All Customers

GET /api/v1/customers

Returns your Customers, newest first, 15 per page.

Query parameterDescription
pageThe page number. Defaults to 1.
typeOnly return individual or business Customers.
statusOnly return Customers with this status, for example verified.

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/customers?type={{TYPE}}&status={{STATUS}}&page={{PAGE}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "data": [
        {
            "uuid": "cus_8mlcKk9cN9HjogohJnYHW0dwD6pmFlZnuowUPjLh",
            "object": "customer",
            "status": "unfinished",
            "type": "individual",
            "first_name": "John",
            "last_name": "Morgan",
            "email": "[email protected]",
            ...
        },
        {
            "uuid": "cus_hceyfUQ5IWz9jzPbo8UbgOVfXT63z3Lpxyaf2XmY",
            "object": "customer",
            "status": "unfinished",
            "type": "business",
            "company_name": "Harbor Demo LLC",
            "email": "[email protected]",
            ...
        }
    ],
    "links": {
        "first": "https://harbor-sandbox.owlpay.com/api/v1/customers?page=1",
        "last": "https://harbor-sandbox.owlpay.com/api/v1/customers?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://harbor-sandbox.owlpay.com/api/v1/customers",
        "per_page": 15,
        "to": 2,
        "total": 2
    }
}
  • To get the next page, call links.next. It is null on the last page.
  • Page size is fixed at 15.

Delete a Customer

DELETE /api/v1/customers/{customer_uuid}

curl --location --request DELETE 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "message": "The customer was deleted successfully.",
    "data": null
}

After a delete:

  • The Customer can't be restored through the API. Create a new Customer instead: it gets a new uuid, and the same email can be used again.
  • Any request for the deleted Customer returns 404 with error code 2001. This includes retrieving it, its onboarding and its RFIs.
  • Creating a transfer for a deleted Customer returns 422 with error code 2005.
  • Transfers already created keep processing. You can still retrieve and list them, but on_behalf_of is null. Completed transfers stay, and they still count in your monthly statement.
  • Harbor doesn't send a webhook for a delete, and nothing else is closed or removed for the Customer, such as linked funding sources.
  • A delete isn't blocked by open transfers or an unfinished onboarding. Deleting a Customer that doesn't exist, or is already deleted, returns 404.

Get an Agreement Link

POST /api/v1/customers/{customer_uuid}/agreement_link

Creates a new agreement link for a Customer, for example if the original link was lost. Optionally, send a redirect_url to send the Customer there after they accept the agreement.

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}/agreement_link' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
  "redirect_url": "{{REDIRECT_URL}}"
}'
{
    "data": {
        "agreement_link": "https://harbor-sandbox.owlpay.com/agreements?uuid=agt_NhJHioyyV3rRlB6u2lxTxZ7z4YDyJJHcXPXGLUDm&redirect_url=https%3A%2F%2Fexample.com%2Fonboarding-done"
    }
}

Each call returns a new link.

Errors

Errors you can get from the Customer endpoints. For the full list, see Error Codes.

StatusCodeWhen
4011001The X-API-KEY header is missing.
4011002The API key is invalid or revoked.
4031006The API key doesn't have the scope for this endpoint.
4032201Your own application isn't verified yet.
4042001The Customer doesn't exist, or was deleted.
4222005A field is missing or invalid, or the email is already used by another Customer.

For example, creating a Customer with an email that is already used:

{
    "message": "The email has already been taken.",
    "code": 2005,
    "error_type": "general.validation_error",
    "errors": {
        "email": [
            "The email has already been taken."
        ]
    }
}

Next Steps

Once the Customer is created, onboard them. See Onboarding. For what each Customer status means, see Status Definitions.


Did this page help you?