BILL Spend & Expense API
Guides
System status

Organizations for BILL partners

As a BILL partner, you can create an organization.

❗️

IMPORTANT

This operation requires partner-level permissions.

  • A sessionId header value generated with /v3/partner/login
  • An appKey header value

Creating an organization

In your POST /v3/organizations request, set the required fields.

FieldDescription
nameOrganization name
addressOrganization address information.

- line1
- city
- zipOrPostalCode
- country
phoneOrganization phone number

See the /v3/organizations API for more information about the other organization fields you can set.

Sample request

In this cURL example, an organization is created with the specified details. The tax, owner, industry, and business category details are added to maintain additional organization information. In addition, mailingAddressSameAsPhysical is set as true for setting the physical address as the mailing address.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/partner/organizations' \
--header 'content-type: application/json' \
--header 'appKey: {application_key}' \
--header 'sessionId: {partner_session_id}' \
--data '{
  "name": "Rice Cakes Inc",
  "address": {
    "line1": "987 Home St",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "phone": "{phone_no}",
  "taxId": "999888777",
  "taxIdType": "EIN",
  "companyOwner": {
    "name": "Noodle Soupsmith",
    "dateOfBirth": "1985-01-01"
  },
  "industry": "Restaurant Caterer or Bar",
  "businessCategory": "LLC",
  "accountType": "BUSINESS",
  "processingOptions": {
    "mailingAddressSameAsPhysical": "true"
  }
}'

Response

In the response, a BILL-generated organization id is available. The value begins with 008.

{
  "id": "{organization_id}",
  "archived": false,
  "name": "Rice Cakes Inc",
  "address": {
    "line1": "987 Home St",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "mailingAddress": {
    "line1": "987 Home St",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "phone": "{phone_no}",
  "companyOwner": {
    "name": "Noodle Soupsmith",
    "dateOfBirth": "1985-01-01"
  },
  "taxId": "**** ****",
  "taxIdType": "EIN",
  "industry": "Restaurant Caterer or Bar",
  "businessCategory": "LLC",
  "accountType": "BUSINESS",
  "processingOptions": {
    "mailingAddressSameAsPhysical": true
  },
  "partnerName": "{partner_name}",
  "createdTime": "2024-12-15T21:06:38.000+00:00",
  "updatedTime": "2024-12-15T21:06:39.000+00:00"
}

You can use the generated organization id for other partner-level and organization-level BILL operations. As a BILL partner, you can create a user for this organization. See Users for BILL partners for more information.

Updated 6 months ago