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.