Customers

Create, update and fetch contracts information.

Received's Customers' APIs allow our users to manage their customers and subscribers. The APIs support operations such as creating a new customer, updating existing customers and fetching customers' related data.

Endpoint on this page
POST https://api.received.ai/api/customers
GET https://api.received.ai/api/entities/<entity_ref>
GET https://api.received.ai/api/customers/names
GET https://api.received.ai/api/entities/names

Don't forget! APIs must include:

  1. Bearer Token - return from the login call

  2. API version - {"Version": "V0"}

Adding Customer For Debit Entity

Adding a new customer for the receiving entity involves registering their details and payment information, enhancing the entity's client base and opening avenues for increased revenue streams.

Add Customer

POST https://api.received.ai/api/customers
Mandatory request 
{
  "name": "Acme",
  "email": "[email protected], [email protected]",
}
Extensive request
{
  "name": "Acme",
  "legal_name": "Acme Inc.",
  "email": "[email protected], [email protected]",
  "ein": "12-3456789",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "country": "United States",
  "country_state": "NY",
  "city": "New York",
  "zip_code": "13601",
  "billing_address": "643 Mundy St, Watertown",
  "shipping_address": "643 Mundy St, Watertown",
  "currency": "USD",
  "tax": 17,
  "entity_ref": "9f9f6a42-fba0-4fb5-ac7a-e83ac2c045a9",
  "net_terms": 30,
  "billing_bank_transfer_details": {
    "billing_account_id": "12345678-1234-1234-1234-1234567890ab"
  },
  "billing_online_payment_details": {
    "auto_charge": true,
    "payment_gateway_id": "87654321-4321-4321-4321-0987654321ba",
    "payment_gateway_card_id": "card_abcdef1234567890"
  },
  "billing_crypto_details": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "tokens": ["BTC", "ETH"]
  },
  "settings": {
    "attach_usage_logs_csv": false,
    "attach_usage_logs_pdf": true
  }
}

Responses

{
  "customer_ref": {{customer_ref}}
}

Request Schema

Term
Type
Description
Example

name*

String

Company name

Acme

email*

String

Company's email addresses comma separated

[email protected], [email protected]

legal_name

String

Company's legal name - documents use

Acme Inc.

ein

Number

Employer identification number

12-3456789

phone

Number

Company's phone number in international format (7-20 digits)

2121234567

country_code

Number

Country code (1-4 digits)

123

country*

String

Company's country of operation

United States

country_state

String

Company's state of operation

NY

city

String

Company's city of operation

New York

zip-code

Number

Company's zip code

10001

billing_address

String

Company's billing address

643 Mundy St, Watertown, New York(NY), 13601

shipping_address

String

Company's shipping address

643 Mundy St, Watertown, New York(NY), 13601

currency

String

The default currency that is used for this company

USD

tax

Number

Value Added Tax - in percentage

17

entity_ref

String

The ID of the related supplier entity

fae8fc36-d321-473f-9890-a9cb16deb4dd

net_terms*

Number

The default net terms used for this company, It must be a positive number or a payment term: "DUE_UPON_RECEIPT", "DUE_UPON_USAGE"

30

billing_bank_transfer_details billing_account_id

Object String

Bank account details The ID of the bank account

{
  "billing_account_id": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f"
}

billing_online_payment_details auto_charge payment_gateway_id payment_gateway_card_id

Object Boolean String String

Online payment details Indicates whether the charging should be automatic or not The ID of the payment gateway The ID of a specific card defined in the payment gateway account, such as Stripe card id

{
  "auto_charge": true,
  "payment_gateway_id": "3a7b0f7d-fdf6-4f54-90f4-2307b73ae85f",
  "payment_gateway_card_id": "card_abcdef1234567890"
}

billing_crypto_details address tokens

Object String Array

The details of the crypto wallet The address of the crypto wallet The crypto tokens that supported by the wallet 

{
  "address": "1Lbcfr7sAHTD9CgdQo3HTMTkV8LK4ZnX71",
  "tokens": ["BTC", "ETH"]
}

settings attach_useage_logs_csv attach_useage_logs_pdf

String Boolean Boolean

Set usage reports for Invoice email:

Attach logs csv to invoice email Attach logs appendix to invoice PDF

{
  "attach_usage_logs_csv": false,
  "attach_usage_logs_pdf": true
}

Response Schema

Term
Type
Description
Exmaple

customer_ref

String

Customer reference

dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c

Get Debit Entity

GET https://api.received.ai/api/entities/<entity_ref>

Responses

{
  "entity_ref": "db93868d-01f6-40dc-8609-0a314969d03b",
  "name": "ACME",
  "legal_name": "ACME Ltd.",
  "email": "[email protected], [email protected]",
  "registration_number": "12-3456789",

  "billing_details": {
    "billing_accounts": [
      {
        "billing_account_id": "0c013466-84f4-48a4-a91b-5cc9808fc3f5",
        "bank_name": "Bank Of America",
        "bank_code": "123",
        "branch": "123",
        "account": "123123",
        "account_name": "US BOA Account",
        "iban": "IL62 0108 0000 0009 9999 999",
        "swift": "BOFAUS3N",
        "routing": "071904779",
        "address": "643 Mundy St, Watertown, New York(NY), 13601",
      }
    ],
    "payment_gateways": [
      {
        "payment_gateway_id": "b59ec2d9-379a-46cf-b69c-fdb5fa47787d",
        "provider": "STRIPE",
        "payment_gateway_card_id": "acct_1OPTJWKoIU7lFy9r",
        "account_name": "US Account"
      }
    ]
  },
  
  "country": "United States",  
  "country_state": "NY",
  "city": "New York",
  "address": "643 Mundy St, Watertown",
  "phone": {
    "countryCode": "1",
    "phone": "2121234567"
  },
  "zip_code": "13601",
}

Explore More APIs

Delves into additional customers methods, broadening your integration capabilities and enhancing secure access

List All Customers

All Customers
GET https://api.received.ai/api/customers/names
Response
{
    "customers": [
        {
            "customer_ref": {{customer_ref}},
            "customer_name": {{customer_name}},
            "customer_legal_name": {{customer_legal_name}}
        }
    ]
}

Filter List Of Customers

Filter list of customers
GET https://api.received.ai/api/customers/names/filter?customer_name={{customer_name}}&orderBy=name&order=ASC
Response
{
    "customers": [
        {
            "customer_ref": {{customer_ref}},
            "customer_name": {{customer_name}},
            "customer_legal_name": {{customer_legal_name}}
        }
    ],
    "count": 1,
    "total": 1
}

Customer Invoices

See invoices API

List All Debit Entities

GET https://api.received.ai/api/entities/names

Response

{
    "entities": [
        {
            "entity_ref": {{entity_ref}},
            "entity_name": {{entity_name}},
            "entity_legal_name": {{entity_legal_name}}
        }
    ]
}

Response Schema

Term
Type
Description
Exmaple

entity_ref

String

The ID of the supplier entity

dcaff9c0-4a9c-4d01-b2dc-0da7efcc616c

entity_name

String

The name of the supplier entity

Acme

entity_legal_name

String

The legal name of the supplier entity - used of documents

Acme Ltd.

PreviousProductsNextContracts

Last updated

Was this helpful?