AboutOwlPayOwlTing
Guides
Contact Us
  1. Core Resources

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
}

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.

Next Steps

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

Updated about 18 hours ago

Did this page help you?