---
updatedAt: 2026-06-29T20:33:19.000Z
---

Fetch the complete documentation index at: https://developer.bill.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# API login

Sign in to your BILL developer account. In the response, your API session is created and a BILL-generated `sessionId` is available. Use the `sessionId` in all subsequent API calls to confirm that you are in a signed-in session.

To create an MFA-trusted API session, set `rememberMeId` and `device` in addition to the required fields. See [MFA setup](https://developer.bill.com/reference/setup) for information about the BILL MFA process.

You can sign out with `POST /v3/logout`. If your API session is inactive for 35 minutes, the session expires and you are automatically signed out.

See [API partner login](https://developer.bill.com/reference/partnerlogin) for information about the additional permissions you get with the API partner login.

**Note**: This section is about authentication for working with the BILL v3 API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for information about authentication for the Spend & Expense API endpoints.

# 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/login": {
      "post": {
        "tags": [
          "authentication"
        ],
        "summary": "API login",
        "description": "Sign in to your BILL developer account. In the response, your API session is created and a BILL-generated `sessionId` is available. Use the `sessionId` in all subsequent API calls to confirm that you are in a signed-in session.\n\nTo create an MFA-trusted API session, set `rememberMeId` and `device` in addition to the required fields. See [MFA setup](https://developer.bill.com/reference/setup) for information about the BILL MFA process.\n\nYou can sign out with `POST /v3/logout`. If your API session is inactive for 35 minutes, the session expires and you are automatically signed out.\n\nSee [API partner login](https://developer.bill.com/reference/partnerlogin) for information about the additional permissions you get with the API partner login.\n\n**Note**: This section is about authentication for working with the BILL v3 API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for information about authentication for the Spend & Expense API endpoints.",
        "operationId": "login",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequestDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "API login response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponseDto"
                }
              }
            }
          },
          "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": {
      "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"
        ]
      },
      "LoginRequestDto": {
        "required": [
          "devKey",
          "organizationId",
          "username"
        ],
        "type": "object",
        "properties": {
          "devKey": {
            "type": "string",
            "description": "Developer key sent to you by BILL when you create a developer account"
          },
          "username": {
            "type": "string",
            "description": "Email address used to sign in to your BILL account"
          },
          "password": {
            "type": "string",
            "description": "Password used to sign in to your BILL account"
          },
          "consoleApiToken": {
            "type": "string",
            "description": "Console API token.\n\nAs a BILL Accountant Console user, use `POST /v3/login` to sign in to a client organization.\n* `username`: Your BILL Accountant Console email address\n* `consoleApiToken`: Your Console API token\n* `devKey`: Developer key of the client organization\n* `organizationId`: Organization ID of the client organization\n\nSee [BILL Accountant Console operations](https://developer.bill.com/docs/bill-accountant-console-operations) for more information."
          },
          "organizationId": {
            "type": "string",
            "description": "Organization ID"
          },
          "rememberMeId": {
            "type": "string",
            "description": "MFA ID. Set this field for creating an MFA-trusted API session.\n\nThis MFA ID is generated when you set `rememberMe` as `true` in your `POST /v3/mfa/challenge/validate` request. This value expires in 30 days.\n\nSee [Validate MFA challenge](https://developer.bill.com/reference/validatechallenge) for more information."
          },
          "device": {
            "type": "string",
            "description": "Mobile device name. This is a nickname for your mobile device. Set this field when you set `rememberMeId`."
          }
        },
        "description": "API login",
        "example": {
          "username": "{{username}}",
          "password": "{{password}}",
          "organizationId": "{{organization_id}}",
          "devKey": "{{developer_key}}"
        }
      },
      "LoginResponseDto": {
        "required": [
          "organizationId",
          "sessionId",
          "trusted",
          "userId"
        ],
        "type": "object",
        "properties": {
          "sessionId": {
            "type": "string",
            "description": "API session ID. Use this value in all subsequent API calls to confirm that you are in a signed-in session."
          },
          "organizationId": {
            "type": "string",
            "description": "Organization ID associated with the signed-in user"
          },
          "userId": {
            "type": "string",
            "description": "BILL-generated ID of the signed-in user"
          },
          "trusted": {
            "type": "boolean",
            "description": "This field is set as `true` if the current API session is MFA-trusted"
          }
        },
        "description": "Login 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"
        ]
      }
    }
  }
}
```