--- updatedAt: 2026-06-29T20:33:19.000Z agentTools: projectIndex: https://developer.bill.com/llms.txt --- # Get organization details Get details about an existing organization. The currently signed-in user must have the `ADMINISTRATOR` user role in the BILL organization to perform this operation. See [Organizations and Users](https://developer.bill.com/docs/organizations-users) in the Guides section for more information, sample requests, and responses. # 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/organizations/{organizationId}": { "get": { "tags": [ "organizations" ], "summary": "Get organization details", "description": "Get details about an existing organization. The currently signed-in user must have the `ADMINISTRATOR` user role in the BILL organization to perform this operation.\n\nSee [Organizations and Users](https://developer.bill.com/docs/organizations-users) in the Guides section for more information, sample requests, and responses.", "operationId": "getOrganization", "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": "organizationId", "in": "path", "required": true, "schema": { "minLength": 1, "type": "string", "description": "BILL-generated ID of the organization. The value begins with `008`.", "example": "{{organization_id}}" } } ], "responses": { "200": { "description": "Get organization details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "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" } } }, "BusinessCategoryResponse": { "type": "string", "description": "Business Category.", "enum": [ "UNDEFINED", "CORPORATION", "LLC", "NON_PROFIT", "GOVERNMENT", "SOLE_PROPRIETOR", "INDIVIDUAL", "TRUST", "UNKNOWN" ] }, "Category": { "type": "string", "enum": [ "REQUEST", "APPLICATION", "SERVER", "DOWNSTREAM" ] }, "CompanyOwner": { "type": "object", "properties": { "name": { "maxLength": 100, "type": "string", "description": "Company owner name" }, "dateOfBirth": { "type": "string", "description": "Company owner date of birth. The value is in the `yyyy-MM-dd` format.", "format": "date" } }, "description": "Company owner." }, "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" ] }, "OrganizationAccountTypeResponse": { "type": "string", "description": "Organization Account Type.", "enum": [ "BUSINESS", "CONTRACTOR", "EMPLOYEE_OR_INDIVIDUAL", "OTHER", "CONSUMER", "UNDEFINED" ] }, "OrganizationProcessingOptions": { "type": "object", "properties": { "mailingAddressSameAsPhysical": { "type": "boolean", "description": "Set as `true` if the mailing address is the same as the physical address. The default value is `true`." }, "individualTransferOut": { "type": "boolean", "description": "Rule for how ACH transfers are made from the organization funding bank account to vendors.\n* Set as `true` for an individual ACH transfer for each payment made.\n* Set as `false` for a single batch ACH transfer for all payments made in a day. The default value is `false`.\n\n**Note**: You can set this field only when you update an organization (`PATCH /v3/organizations/{organizationId}`)." }, "individualTransferIn": { "type": "boolean", "description": "Rule for how ACH transfers are made from customers to the organization funding bank account.\n* Set as `true` for an individual ACH transfer for each payment received.\n* Set as `false` for a single batch ACH transfer for all payments received in a day. The default value is `false`.\n\n**Note**: You can set this field only when you update an organization (`PATCH /v3/organizations/{organizationId}`)." } }, "description": "User provided options for having the same mailing address as the physical address." }, "OrganizationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "BILL-generated ID of the organization. The value begins with `008`." }, "archived": { "type": "boolean", "description": "Set as `true` if the organization is archived. You cannot archive an organization with the API." }, "name": { "type": "string", "description": "Organization name" }, "displayName": { "type": "string", "description": "Organization display name (DBA trade name)" }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressResponse" }, { "description": "Organization physical address" } ] }, "mailingAddress": { "allOf": [ { "$ref": "#/components/schemas/AddressResponse" }, { "description": "Organization mailing address" } ] }, "phone": { "type": "string", "description": "Organization phone number" }, "companyOwner": { "allOf": [ { "$ref": "#/components/schemas/CompanyOwner" }, { "description": "Company owner information" } ] }, "taxId": { "type": "string", "description": "Organization tax ID. This value is required by the IRS for tax purposes." }, "taxIdType": { "allOf": [ { "$ref": "#/components/schemas/TaxIdTypeResponse" }, { "description": "Organization tax ID type." } ] }, "industry": { "type": "string", "description": "Organization industry" }, "businessCategory": { "allOf": [ { "$ref": "#/components/schemas/BusinessCategoryResponse" }, { "description": "Organization business category." } ] }, "accountType": { "allOf": [ { "$ref": "#/components/schemas/OrganizationAccountTypeResponse" }, { "description": "Organization account type." } ] }, "processingOptions": { "allOf": [ { "$ref": "#/components/schemas/OrganizationProcessingOptions" }, { "description": "Organization processing options" } ] }, "partnerName": { "type": "string", "description": "Partner name.\n\nThis field is available only when select BILL partners create an organization. Partner name is part of the information that BILL uses to identify partners." }, "createdTime": { "type": "string", "description": "Created date and time", "format": "date-time" }, "updatedTime": { "type": "string", "description": "Updated date and time", "format": "date-time" } }, "description": "Organization 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" ] }, "TaxIdTypeResponse": { "type": "string", "description": "The enum Tax id type enum.", "enum": [ "EIN", "SSN", "UNDEFINED" ] } } } } ```