> ## Documentation Index > Fetch the complete documentation index at: https://docs.onboardme.app/llms.txt > Use this file to discover all available pages before exploring further. # Create an adhoc proposal > Create an adhoc proposal. export function DensityStyles() { return ; } ## OpenAPI ````yaml POST /api/v1/proposals openapi: 3.0.4 info: title: OnboardMe External API description: "Partner integration API for OnboardMe. All routes are under `/api/v1/…` on your **regional** API host.\r\n\r\n---\r\n\r\n## Regional base URLs\r\n\r\nUse the host that matches where the practice is hosted (a practice is tied to one region).\r\n\r\n| Region | Base URL |\r\n| ------ | -------- |\r\n| Australia & New Zealand | `https://anzapi.onboardme.app` |\r\n| United Kingdom | `https://ukapi.onboardme.app` |\r\n| South Africa | `https://zaapi.onboardme.app` |\r\n\r\nIn your HTTP client, pick the matching **Server** / base URL (or set `baseUrl` to one of the URLs above).\r\n\r\nExample: `GET https://ukapi.onboardme.app/api/v1/auth/validate`\r\n\r\n---\r\n\r\n## Authentication\r\n\r\n**Production integrations (recommended):** send both headers on every request:\r\n\r\n- **`X-OM-Auth-ID`** — Client ID (GUID from OnboardMe practice settings)\r\n- **`X-OM-Auth-Key`** — Client secret paired with that Client ID\r\n\r\n**Postman / Swagger Try it out:** use **Authorize** (HTTP Basic) with **Client ID** as the username and **Client secret** as the password. In Postman, set Basic Auth **once on the collection** so every request inherits it — you do not need auth on each request or two separate header fields.\r\n\r\nHTTPS only. Credentials are scoped to one practice; this API does not use end-user passwords.\r\n\r\n---\r\n\r\n## Partner onboarding\r\n\r\n1. Obtain **Client ID** and **secret** from the practice administrator (OnboardMe).\r\n2. Select the **correct regional base URL** (ANZ, UK, or ZA); practices do not span regions.\r\n3. Call `GET /api/v1/auth/validate` to confirm access and read `canWrite` before using any write endpoint.\r\n4. Run an initial **full** import, then use `lastUpdated` on list endpoints for **incremental** sync.\r\n5. On **429 Too Many Requests**, honour `Retry-After` and backoff; avoid polling faster than you need.\r\n\r\n---\r\n\r\n## Pagination and sync\r\n\r\nList endpoints support optional `pageNumber` (1-based, up to 10000) and `lastUpdated` (UTC). Use `lastUpdated` for incremental sync: only rows changed on or after that instant. `lastUpdated` must not be in the future.\r\n\r\n---\r\n\r\n## Rate limits\r\n\r\nPer Client ID (default: 60/minute, 1000/hour, 10000/day). **429** responses include JSON details and headers: `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.\r\n\r\n---\r\n\r\n## Write access\r\n\r\nCreating or updating data requires `canWrite: true` from `/api/v1/auth/validate`. Read-only clients get **403** on write routes.\r\n\r\nLead endpoints under **`/api/v1/leads`** support listing, detail, notes, create, and **convert-to-client** (promote a lead to an Active client).\r\n\r\n**Contacts** (`/api/v1/contacts/list` and `/api/v1/entities/{entityKey}/contacts`) expose people linked to clients — list, create, and update.\r\n\r\n**ID verifications** — **`POST /api/v1/id-verifications/send`** starts identity verification (optionally with AML via **`includeAml`**). **`POST /api/v1/id-verifications/aml-checks`** runs a standalone **standard** or **extensive** AML screening on an existing client (`entityKey`). Download a verification certificate PDF with **`GET /api/v1/id-verifications/entities/{entityKey}/certificate`**.\r\n\r\n**Onboarding documents** — **`GET /api/v1/onboardings/{key}/documents`** lists requirements per client entity (`isUploaded` / `isBypassed`). Download one file via a short-lived signed S3 URL: **`GET …/entities/{entityOnboardingId}/documents/{documentId}`**. Download all uploaded files as a zip: **`GET …/entities/{entityOnboardingId}/documents/zip`**.\r\n\r\n**Bills** — **`GET /api/v1/bills/list`** lists invoices by **bill date** range (`startDate` / `endDate`). **`GET /api/v1/bills/{billingId}`** returns detail including ledger fields (`externalId`, `externalNumber`, `externalUrl`). **`GET /api/v1/bills/{billingId}/pdf`** downloads the OnboardMe invoice PDF. **`POST /api/v1/bills`** creates an **adhoc** bill for an Active client entity only (no engagement / onboarding entity link; requires `canWrite`; does **not** push to Xero — stores `sendBill` / `syncNow`). When Xero is connected, lines need a revenue account (`extAccountID`) or sale item plus tax (`extTaxID`); use **`GET /api/v1/bills/ledger/status|accounts|tax-rates|branding-themes`**.\r\n\r\n**Proposals** — List a client's proposals with **`GET /api/v1/proposals/list?entityKey=`**. Load previous **services, invoices, recurring billings, and jobs** via **`GET /api/v1/proposals/{key}/pricing`** (or full **`GET /api/v1/proposals/{key}`**). **`POST /api/v1/proposals/{key}/duplicate`** copies pricing, billings, and jobs into a new draft. **`POST /api/v1/proposals/{key}/renew`** does the same and marks the original Renewed (**`GET …/renew-preview`** first for signatory choice). **`POST /api/v1/proposals/from-template`** creates from a saved template. **`POST /api/v1/proposals`** creates an **adhoc** proposal with caller-supplied **services**, optional **XPM jobs**, **FYI jobs**, and **billings**. Catalogs: **`GET /api/v1/proposals/services`**, **`…/xpm-job-templates`**, **`…/xpm-job-categories`**, **`…/xpm-staff`**, **`…/fyi-job-templates`**, **`…/fyi-job-states`**.\r\n\r\n**Recurring billing** — **`GET /api/v1/recurring-billing/list`**, **`GET /api/v1/recurring-billing/{recurringBillingId}`**, and **`GET …/runs`** for schedule list, detail, and generated-run history. Ledger invoice numbers/URLs appear on generated bills, not on the schedule itself.\r\n\r\n---\r\n\r\n## Outbound webhooks\r\n\r\nRegister a subscriber URL with **`POST /api/v1/webhooks`** (requires `canWrite`). Supported event keys are listed at **`GET /api/v1/webhooks/events`** (e.g. `proposal.accepted`, `eform.submitted`). One subscription per event; repeat subscribe with the same URL for multiple events.\r\n\r\n**Subscribe response (`201`):** `{ \"id\", \"webhookSecret\" }` — store `webhookSecret` immediately; it is **not** returned again on list/load.\r\n\r\n**Deliveries:** OnboardMe `POST`s JSON to your URL. Each request includes:\r\n\r\n| Header | Description |\r\n| ------ | ------------- |\r\n| `X-Om-Event` | Event key (e.g. `proposal.accepted`) |\r\n| `X-Om-Event-Id` | Unique idempotency key for this event |\r\n| `X-Om-Timestamp` | Unix time (seconds, UTC) used when signing |\r\n| `X-Om-Signature` | `sha256=` HMAC (see below) |\r\n\r\n**Signature verification (recommended on your server):**\r\n\r\n1. Read the **raw** request body bytes (do not re-serialize JSON).\r\n2. Build `canonical = {X-Om-Timestamp} + \".\" + {rawBody}`.\r\n3. Compute `expected = \"sha256=\" + HMAC_SHA256_UTF8(webhookSecret, canonical)` (hex **lowercase**).\r\n4. Compare `expected` to `X-Om-Signature` using a constant-time comparison; reject on mismatch.\r\n\r\nThe delivery JSON schema is documented as **`ApiWebhookDeliveryEventDTO`** in Schemas (see **Webhooks** operations). Test deliveries: **`POST /api/v1/webhooks/{id}/test`**.\r\n\r\n---\r\n\r\n## Errors\r\n\r\n- **400** — validation (`message` in body).\r\n- **401** — bad or missing credentials.\r\n- **404** — resource not in the practice (`message`).\r\n\r\nSchemas below include **illustrative** example values; live responses use your data." contact: name: OnboardMe Support email: support@onboardme.app version: v1 servers: - url: https://anzapi.onboardme.app description: Australia & New Zealand — ANZ-hosted practices - url: https://ukapi.onboardme.app description: United Kingdom — UK-hosted practices - url: https://zaapi.onboardme.app description: South Africa — ZA-hosted practices security: - ApiClientCredentials: [] paths: /api/v1/proposals: post: tags: - Proposals summary: Create an adhoc proposal description: "Creates a **full proposal** for an existing client **without** a proposal template: services, one-off and recurring billing, payment-details collection, identity verification, and optional onboarding after acceptance.\r\n\r\n**Request**\r\n\r\n- **`userKey`** — staff member creating/sending the proposal (**`userKey`** from **GET `/api/v1/users/list`**).\r\n- **`entityKey`** — existing client (same key as **GET `/api/v1/entities/{key}`**).\r\n- **`name`** — proposal name (the client display name is appended).\r\n- **`sendToClient`** — when **true**, the proposal is sent after creation (or submitted for internal approval first when required). When **false**, it is saved as a **draft**.\r\n- **`services`** — at least one line. **`serviceID`** from **GET `/api/v1/proposals/services`**. Optional overrides: `quantity`, `price`, `taxAmount`, `packageNumber`, `isOptional`, `discountPerc`, `discountAmount`, `serviceDetail`.\r\n- **`xpmJobs`** — optional. Each job needs **`name`** and **`templateUuid`** from **GET `/api/v1/proposals/xpm-job-templates`**. Optional: `categoryId`, `partnerUuid` / `managerUuid`, dates, `description`, `refNo`, `budget`. XPM must be connected.\r\n- **`fyiJobs`** — optional. Each job needs **`jobName`**, **`managerEmail`**, **`partnerEmail`**. Optional **`fyiTemplateId`** and **`state`**. FYI Elite must be connected.\r\n- **`invoices`** — optional one-off proposal billings (not **POST `/api/v1/bills`**). Each invoice needs `billDate`, `dueDate`, and `lineItems` with `amount`, `narration`, and `taxAmount` or `taxPercent`. Optional ledger ids: `extAccountID`, `extItemID`, `extTaxID`. **`billNow`**: `0` neither, `1` upfront, `2` on completion.\r\n- **`recurringBillings`** — optional OnboardMe recurring schedules. Each needs **`frequency`** (`daily`, `weekly`, `fortnightly`, `monthly`, `quarterly`, `annually`), **`startDate`**, and `lineItems` (same shape as invoices). Optional: `endDate`, `nextRunDate` (defaults to `startDate`), `dueDays`, `billDetails`, `refNo`, `brandingThemeID`, `sendBill`, `packageNumber`. **`billNow`**: `0` neither or `2` on completion.\r\n- **`requestPaymentDetails`** — when **true**, collect payment method on acceptance. **`paymentDetailsType`**: `0` all (default), `1` card, `2` bank account.\r\n- **`identityVerification`** — when **true** (and **`onboarding`** is omitted), run IDV on the proposal client. Requires **`verificationMethod`**: `Basic`, `Standard`, `Enhanced`, `Comprehensive`, `Annature Identity Only`, or `Annature Identity + AML`. Individual / Sole Trader only.\r\n- **`identityPeople`** — optional extra people to verify. Existing person: **`entityKey`**. New person: **`name`**, **`surname`**, optional `email` / `mobile`. Each needs **`verificationMethod`**. **`includeEngagement`**: `false` (default) is IDV-only; `true` includes them on the engagement.\r\n- **`onboarding`** — optional. When present, creates onboarding to send **after acceptance**. **`clients`** uses the same shape as **POST `/api/v1/onboardings/create`** (existing `entityKey` or quick-add with type/name, plus `requireTaxDetails`, `identityVerification`, `requireDocuments` / `documents`, `requestAccountingFileAccess`). If `clients` is empty, the proposal client is added automatically. Optional **`recipients`**: `name`, `surname`, `email`, `mobile`, `sendSms`. Omit recipients to derive them from signatories / onboarding clients. Put IDV on **`onboarding.clients`** (or top-level **`identityVerification`**, which is copied onto the proposal client row).\r\n\r\nOptional header fields: `note`, `startDate`, `endDate`, `startOnAcceptance`, `currencyID`, `lengthID`, `terms`, `refNo`, `expiryDate`, `sendSms`.\r\n\r\n**Response**\r\n\r\n- **`engagementKey`** — use with **GET `/api/v1/proposals/{key}`**.\r\n- **`sentToClient`** — **true** when sent (or sent for approval); **false** when left as a draft.\r\n\r\nWhen **`sendToClient`** is **true** but sending fails, the proposal is **left as a draft** and **`sentToClient`** is **false**; **`engagementKey`** is still returned.\r\n\r\nWrite access is required (**`canWrite: true`** from **`GET /api/v1/auth/validate`**).\r\n\r\n**429** — rate limit exceeded." requestBody: content: application/json: schema: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateRequestDTO text/json: schema: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateRequestDTO application/*+json: schema: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateRequestDTO responses: '200': description: OK content: text/plain: schema: $ref: >- #/components/schemas/Application.APIData.DataObjects.EngagementFromTemplateResponseDTO application/json: schema: $ref: >- #/components/schemas/Application.APIData.DataObjects.EngagementFromTemplateResponseDTO text/json: schema: $ref: >- #/components/schemas/Application.APIData.DataObjects.EngagementFromTemplateResponseDTO '400': description: Bad Request content: text/plain: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' text/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' text/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' text/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' text/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '429': description: Too Many Requests content: text/plain: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' text/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '500': description: Internal Server Error components: schemas: Application.APIData.DataObjects.ProposalCreateRequestDTO: type: object properties: userKey: type: string format: uuid entityKey: type: string format: uuid sendToClient: type: boolean name: type: string nullable: true note: type: string nullable: true startDate: type: string format: date-time nullable: true endDate: type: string format: date-time nullable: true startOnAcceptance: type: boolean nullable: true currencyID: type: integer format: int32 nullable: true lengthID: type: integer format: int32 nullable: true terms: type: integer format: int32 nullable: true refNo: type: string nullable: true services: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateServiceDTO nullable: true xpmJobs: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateXpmJobDTO nullable: true fyiJobs: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateFyiJobDTO nullable: true invoices: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateInvoiceDTO nullable: true recurringBillings: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateRecurringBillingDTO nullable: true requestPaymentDetails: type: boolean paymentDetailsType: type: integer format: int32 nullable: true sendSms: type: boolean nullable: true expiryDate: type: string format: date-time nullable: true identityVerification: type: boolean verificationMethod: type: string nullable: true identityPeople: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateIdentityPersonDTO nullable: true onboarding: $ref: >- #/components/schemas/Application.APIData.DataObjects.ProposalCreateOnboardingDTO additionalProperties: false example: userKey: 11111111-2222-3333-4444-555555555555 entityKey: 2c4f6a88-1b3d-5e7f-90ab-cdef12345678 name: FY26 tax engagement sendToClient: false startOnAcceptance: true note: Adhoc proposal with custom services and jobs. services: - serviceID: 12040 quantity: 1 packageNumber: 1 xpmJobs: - name: Income tax return templateUuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee fyiJobs: - jobName: Income tax return fyiTemplateId: '10492' state: Planned managerEmail: manager@practice.example partnerEmail: partner@practice.example invoices: - billDate: '2026-07-01' dueDate: '2026-07-31' billNow: 1 lineItems: - amount: 2450 taxPercent: 10 narration: Annual tax return serviceID: 12040 Application.APIData.DataObjects.EngagementFromTemplateResponseDTO: type: object properties: engagementKey: type: string format: uuid sentToClient: type: boolean additionalProperties: false example: engagementKey: 8f9e2b1c-3d4a-5e6f-7890-abcdef012345 sentToClient: true Microsoft.AspNetCore.Mvc.ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} Application.APIData.DataObjects.ProposalCreateServiceDTO: type: object properties: serviceID: type: integer format: int32 quantity: type: number format: double nullable: true price: type: number format: double nullable: true taxAmount: type: number format: double nullable: true packageNumber: type: integer format: int32 nullable: true isOptional: type: boolean discountPerc: type: number format: double nullable: true discountAmount: type: number format: double nullable: true serviceDetail: type: string nullable: true additionalProperties: false Application.APIData.DataObjects.ProposalCreateXpmJobDTO: type: object properties: name: type: string nullable: true templateUuid: type: string format: uuid categoryId: type: string format: uuid nullable: true description: type: string nullable: true startDate: type: string format: date-time nullable: true dueDate: type: string format: date-time nullable: true refNo: type: string nullable: true budget: type: number format: double nullable: true partnerUuid: type: string format: uuid nullable: true managerUuid: type: string format: uuid nullable: true additionalProperties: false Application.APIData.DataObjects.ProposalCreateFyiJobDTO: type: object properties: jobName: type: string nullable: true fyiTemplateId: type: string nullable: true state: type: string nullable: true type: type: string nullable: true startDate: type: string format: date-time nullable: true dueDate: type: string format: date-time nullable: true managerEmail: type: string nullable: true partnerEmail: type: string nullable: true sourceID: type: string nullable: true additionalProperties: false Application.APIData.DataObjects.ProposalCreateInvoiceDTO: type: object properties: billDate: type: string format: date dueDate: type: string format: date billDetails: type: string nullable: true refNo: type: string nullable: true billNow: type: integer format: int32 nullable: true syncNow: type: boolean nullable: true sendBill: type: boolean nullable: true brandingThemeID: type: string nullable: true packageNumber: type: integer format: int32 nullable: true lineItems: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.BillCreateLineItemDTO nullable: true additionalProperties: false Application.APIData.DataObjects.ProposalCreateRecurringBillingDTO: type: object properties: frequency: type: string nullable: true startDate: type: string format: date endDate: type: string format: date nullable: true nextRunDate: type: string format: date nullable: true dueDays: type: integer format: int32 nullable: true billDetails: type: string nullable: true refNo: type: string nullable: true brandingThemeID: type: string nullable: true sendBill: type: boolean nullable: true billNow: type: integer format: int32 nullable: true packageNumber: type: integer format: int32 nullable: true lineItems: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.BillCreateLineItemDTO nullable: true additionalProperties: false Application.APIData.DataObjects.ProposalCreateIdentityPersonDTO: type: object properties: entityKey: type: string format: uuid nullable: true name: type: string nullable: true surname: type: string nullable: true email: type: string nullable: true mobile: type: string nullable: true verificationMethod: type: string nullable: true includeEngagement: type: boolean additionalProperties: false Application.APIData.DataObjects.ProposalCreateOnboardingDTO: type: object properties: clients: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.OnboardingClientCreateDTO nullable: true recipients: type: array items: $ref: >- #/components/schemas/Application.APIData.DataObjects.OnboardingRecipientCreateDTO nullable: true additionalProperties: false Application.APIData.DataObjects.BillCreateLineItemDTO: type: object properties: amount: type: number format: double taxAmount: type: number format: double nullable: true taxPercent: type: number format: double nullable: true total: type: number format: double nullable: true narration: type: string nullable: true extAccountID: type: integer format: int64 nullable: true extItemID: type: integer format: int32 nullable: true extTaxID: type: integer format: int32 nullable: true orderID: type: integer format: int32 nullable: true serviceID: type: integer format: int32 nullable: true additionalProperties: false Application.APIData.DataObjects.OnboardingClientCreateDTO: type: object properties: entityKey: type: string format: uuid nullable: true clientCode: type: string nullable: true entityTypeId: type: integer format: int32 nullable: true entityType: type: string nullable: true name: type: string nullable: true surname: type: string nullable: true email: type: string nullable: true mobile: type: string nullable: true requireTaxDetails: type: boolean identityVerification: type: boolean verificationMethod: type: string nullable: true requireDocuments: type: boolean documents: type: array items: type: string nullable: true requestAccountingFileAccess: type: boolean accountingFileInviteName: type: string nullable: true additionalProperties: false Application.APIData.DataObjects.OnboardingRecipientCreateDTO: type: object properties: name: type: string nullable: true surname: type: string nullable: true email: type: string nullable: true mobile: type: string nullable: true sendSms: type: boolean additionalProperties: false securitySchemes: ApiClientCredentials: type: http description: >- Swagger / Postman only: **Client ID** as username, **Client secret** as password. In Postman, set this once on the **collection** (Authorization → Basic Auth) so all requests inherit. For production server-to-server code, prefer **`X-OM-Auth-ID`** and **`X-OM-Auth-Key`** headers. scheme: basic ````