--- updatedAt: 2026-06-29T20:33:19.000Z agentTools: projectIndex: https://developer.bill.com/llms.txt --- # Get customer details Get details about an existing customer. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "BILL v3 API", "description": "BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.\n\nThe BILL v3 API gives you access to the same infrastructure that powers the AP, AR, and S&E products. In addition, you can receive real-time event notifications with webhooks.\n\nThe BILL Developer Documentation is available at [developer.bill.com](https://developer.bill.com/docs/home).\n\n## Quickstart\nSign-up and generate a developer key for working with the BILL v3 API. With this key, you can build with the AP, AR, BILL network, and webhook workflows. See [Sandbox API sign up](https://developer.bill.com/docs/api-sandbox-sign-up) for more information.\n\n### Spend & Expense API\nAn API token is required for working with the Spend & Expense API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for more information.\n\n### BILL v3 API in Postman\nWith this collection, you have access to the BILL v3 API in Postman. When you save your sandbox API credentials as environment variables in Postman, you can simply refer to the variables when you are testing with the BILL v3 API. See [BILL v3 API in Postman](https://developer.bill.com/docs/bill-v3-api-in-postman) for more information.", "version": "1" }, "servers": [ { "url": "https://gateway.stage.bill.com/connect", "description": "sandbox" } ], "paths": { "/v3/customers/{customerId}": { "get": { "tags": [ "customers" ], "summary": "Get customer details", "description": "Get details about an existing customer.", "operationId": "getCustomer", "parameters": [ { "name": "sessionId", "in": "header", "schema": { "type": "string", "description": "API session ID generated with `/v3/login`", "nullable": true, "example": "{{session_id}}" } }, { "name": "devKey", "in": "header", "schema": { "type": "string", "description": "Developer key generated with your BILL developer account", "nullable": true, "example": "{{developer_key}}" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "minLength": 1, "type": "string", "description": "BILL-generated ID of the customer. The value begins with `0cu`.", "example": "{{customer_id}}" } } ], "responses": { "200": { "description": "Get customer details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponseDto" } } } }, "4XX": { "description": "List of errors.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BdcError" } } } } }, "5XX": { "description": "List of errors.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BdcError" } } } } } } } } }, "components": { "schemas": { "AddressResponse": { "required": [ "city", "country", "line1", "zipOrPostalCode" ], "type": "object", "properties": { "line1": { "minLength": 1, "pattern": "^.{0,1000}$", "type": "string", "description": "Address line 1" }, "line2": { "pattern": "^.{0,100}$", "type": "string", "description": "Address line 2" }, "city": { "minLength": 1, "pattern": "^.{0,100}$", "type": "string", "description": "Address city" }, "stateOrProvince": { "pattern": "^.{0,100}$", "type": "string", "description": "State or province" }, "zipOrPostalCode": { "minLength": 1, "pattern": "^.{0,30}$", "type": "string", "description": "Zip or postal code" }, "country": { "allOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "description": "Country code (ISO2)" } ] }, "countryName": { "type": "string", "description": "Country name." } }, "description": "Address response." }, "BdcError": { "required": [ "category", "code", "severity", "timestamp" ], "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "code": { "type": "string" }, "severity": { "$ref": "#/components/schemas/Severity" }, "category": { "$ref": "#/components/schemas/Category" }, "message": { "type": "string" }, "params": { "type": "array", "items": { "$ref": "#/components/schemas/Param" } }, "detail": { "type": "string" }, "help": { "type": "string" } } }, "Category": { "type": "string", "enum": [ "REQUEST", "APPLICATION", "SERVER", "DOWNSTREAM" ] }, "CountryCode": { "type": "string", "description": "Enumeration based on the ISO2 country code specification.", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CV", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IN", "IO", "IQ", "IS", "IT", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MH", "MK", "ML", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "ST", "SV", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "CurrencyCode": { "type": "string", "description": "Enumeration based on the ISO2 country code specification.", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SLL", "SOS", "SPL", "SRD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TVD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XCD", "XDR", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWD" ] }, "CustomerAccountTypeResponse": { "type": "string", "description": "CustomerAccountType.", "enum": [ "NONE", "BUSINESS", "PERSON", "UNDEFINED" ] }, "CustomerBalance": { "type": "object", "properties": { "amount": { "type": "number" } }, "description": "The type CustomerBalance dto." }, "CustomerContact": { "type": "object", "properties": { "firstName": { "maxLength": 100, "type": "string", "description": "First name" }, "lastName": { "maxLength": 100, "type": "string", "description": "Last name" } }, "description": "Customer contact." }, "CustomerResponseDto": { "required": [ "email", "name" ], "type": "object", "properties": { "id": { "type": "string", "description": "BILL-generated ID of the customer. The value begins with `0cu`." }, "archived": { "type": "boolean", "description": "Set as `true` if the customer is archived." }, "name": { "type": "string", "description": "Customer name" }, "companyName": { "type": "string", "description": "Customer company name. This field is overridden when you connect with a customer in the BILL network." }, "contact": { "allOf": [ { "$ref": "#/components/schemas/CustomerContact" }, { "description": "Customer contact information" } ] }, "email": { "type": "string", "description": "Customer email address" }, "phone": { "pattern": "^.{0,20}$", "type": "string", "description": "Customer phone number. This field is overridden when you connect with a customer in the BILL network." }, "fax": { "pattern": "^.{0,20}$", "type": "string", "description": "Customer fax number" }, "description": { "type": "string", "description": "Customer description" }, "invoiceCurrency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyCode" }, { "description": "Invoice currency. Three-letter abbreviation." } ] }, "accountType": { "allOf": [ { "$ref": "#/components/schemas/CustomerAccountTypeResponse" }, { "description": "Customer account type" } ] }, "paymentTermId": { "type": "string", "description": "BILL-generated ID of the payment term. Use payment terms to set the number of days the customer has to clear an invoice." }, "accountNumber": { "type": "string", "description": "Customer account number. The number appears in customer invoices." }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/AddressResponse" }, { "description": "Customer billing address. This information is overridden when you connect with a customer in the BILL network." } ] }, "shippingAddress": { "allOf": [ { "$ref": "#/components/schemas/AddressResponse" }, { "description": "Customer shipping address. This information is overridden when you connect with a customer in the BILL network." } ] }, "balance": { "allOf": [ { "$ref": "#/components/schemas/CustomerBalance" }, { "description": "Current balance to be paid by the customer" } ] }, "hasBankAccount": { "type": "boolean", "description": "Set as `true` if the customer bank account is added" }, "authorizedToCharge": { "type": "boolean", "description": "Set as `true` if your organization is authorized to charge the customer for invoices" }, "createdTime": { "type": "string", "description": "Created date and time", "format": "date-time" }, "updatedTime": { "type": "string", "description": "Updated date and time", "format": "date-time" } }, "description": "Customers response." }, "Param": { "required": [ "name", "value" ], "type": "object", "properties": { "additional": { "type": "object", "additionalProperties": { "type": "string" } }, "name": { "minLength": 1, "type": "string" }, "value": { "minLength": 1, "type": "string" } } }, "Severity": { "type": "string", "enum": [ "ERROR", "WARNING", "INFORMATION" ] } } } } ```