Create and send an onboarding job

An onboarding is a job: one recipient, and one or more clients that recipient completes details for. The API creates the same job the app creates. It does not invent a lighter version. Write access is required to create. Listing and downloading documents works with a read credential.

Who is sending it

userKey is the staff member OnboardMe records as the creator. Take it from GET /api/v1/users/list. Do not hard-code a key from another practice or region.

The recipient

recipient is a single person. Required: name, surname, and email. Optional: mobile, and sendSms when you want an SMS as well as the email. SMS is billed from the wallet when sendToRecipient is true.

Each client row

clients is one or more rows, in the order you want them on the job. Already in the CRM. Set entityKey from GET /api/v1/entities. Name and type come from the stored client. You can still set the flags below, and you can override clientCode. Quick-add. Omit entityKey. Set entityTypeId or entityType from GET /api/v1/settings/entity-types (Individual, Company, and the practice’s other types). Set name, and surname when the type requires it. Optional clientCode becomes the practice client code on the new entity. Optional email and mobile are stored on the new client. The create response returns clients in that same order. Each item has entityOnboardingId, entityKey, and clientCode. The job itself comes back as:

Field	Keep it because
`onboardingKey`	The job id for get, list, and document calls
`sentToRecipient`	`true` only when the invitation was sent
`recipientKey`	The recipient row
`recipientAccessUrl`	The link the recipient uses. When you do not email them yourself, this is the URL to deliver

Already in the CRM. Set entityKey from GET /api/v1/entities. Name and type come from the stored client. You can still set the flags below, and you can override clientCode. Quick-add. Omit entityKey. Set entityTypeId or entityType from GET /api/v1/settings/entity-types (Individual, Company, and the practice’s other types). Set name, and surname when the type requires it. Optional clientCode becomes the practice client code on the new entity. Flags on either path:

Flag	Effect
`requireTaxDetails`	Ask for tax details
`requireDocuments`	Ask for documents. `documents` is the list of document names
`requestAccountingFileAccess`	Ask for accounting-file access
`identityVerification`	Run ID verification. Individuals and sole traders only

When identityVerification is true, verificationMethod is required:

Method	What the client does
`Basic`	Manual document collection. No automated ID check
`Standard`	Identity verification only
`Enhanced`	Identity verification plus basic AML
`Comprehensive`	Identity verification plus extensive AML
`Annature Identity Only`	Annature identity (`type=standard`). Annature must be connected. Legacy alias `Annature`
`Annature Identity + AML`	Annature identity plus AML (`type=enhanced`). Annature must be connected

Omit identityVerification or set it false to skip ID checks on that client.

{
  "userKey": "11111111-2222-3333-4444-555555555555",
  "sendToRecipient": false,
  "recipient": {
    "name": "Sam",
    "surname": "Nguyen",
    "email": "[email protected]",
    "mobile": "+61 412 000 222"
  },
  "clients": [
    {
      "entityKey": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "requireTaxDetails": true,
      "requireDocuments": true,
      "documents": ["Trust deed", "Photo ID"],
      "identityVerification": true,
      "verificationMethod": "Standard"
    }
  ]
}

Send, or keep a draft

sendToRecipient: false saves the job and stops. No email, no wallet charge, no subscription unit. sendToRecipient: true uses the same billing as Send in the app:

Onboarding request units come from the subscription, then the wallet.
Identity verification and AML (Enhanced and Comprehensive) come from the wallet.
SMS comes from the wallet when sendSms is set.
Promotional free-verification rules apply where the practice has them.

Those costs are checked before the job is written. If funds are short, the response is 400 and nothing is persisted. Fix the wallet or subscription and call again with the same body. You will not have a draft to clean up. Other send failures after the job exists (for example a misconfigured mail setting) also return 400. In those rarer cases the job can remain as a draft. Load it with GET /api/v1/onboardings/{onboardingKey} and do not create a duplicate until you confirm the first one is absent.

Find it later

GET /api/v1/onboardings/list lists jobs for the practice. GET /api/v1/onboardings/{onboardingKey} is one job. Store onboardingKey from the create response, and each client’s entityOnboardingId when you download that client’s files.

Documents they uploaded

GET /api/v1/onboardings/{onboardingKey}/documents is the checklist for every client on the job, the same list as Notes & Docs in the app. Soft-deleted rows are omitted. Each entity includes entityKey, entityOnboardingId, name, surname, entityTypeName, and a documents array.

Document field	Meaning
`documentId`	Id for the single-file download
`documentRequested`	The requirement label
`fileName`	Stored file name once uploaded, otherwise null
`isUploaded`	A file is present
`uploadedOn`	UTC upload time
`isBypassed`	Staff bypassed the requirement
`bypassReason`	Optional reason
`isUserUploaded`	An extra upload, not a named requirement

Pending means isUploaded and isBypassed are both false. Downloads return a signed URL (url, fileName, expiresAt). Download it promptly. Do not store the URL.

Call	When
`GET /api/v1/onboardings/{onboardingKey}/entities/{entityOnboardingId}/documents/{documentId}`	One file. Only when `isUploaded` is true
`GET /api/v1/onboardings/{onboardingKey}/entities/{entityOnboardingId}/documents/zip`	Every file for that client row

Proposals can create this same onboarding to send after acceptance, using an onboarding block on POST /api/v1/proposals. See Proposals.

Onboarding reference

Create, list, get, and the document downloads.

Core Concepts

Guides

Create and send an onboarding job

Who is sending it

The recipient

Each client row

Send, or keep a draft

Find it later

Documents they uploaded

Onboarding reference

​Who is sending it

​The recipient

​Each client row

​Send, or keep a draft

​Find it later

​Documents they uploaded

Onboarding reference

Who is sending it

The recipient

Each client row

Send, or keep a draft

Find it later

Documents they uploaded