B5.ly Business Portal
All articles
Developer

Integrate with the Portal API

Use your own assessment interface while keeping clients, reports and credits in your Portal account. The API is server-to-server: keep the key on your server, never in browser or mobile code. Use the backend address supplied for your environment followed by /partner/v1. Portal v2 is the product version; /partner/v1 is the API version.

Set up access

In Settings → Developer, name your key and create it. New keys support the full integration, including connection checks. Older connection-only keys retain their limited permissions; create a new key if you need assessment and report access. Integration keys can update clients, manage API-created assessments, read all entitled full reports and spend credits in their account. Five keys may be active at once; each expires after 90 days. Revoke a key to stop its access.

Send Authorization: Bearer YOUR_KEY with every request. No provider ID is needed. Requests are limited to 60 per key per minute; after 429, wait for the Retry-After interval. Keys also stop working when their issuing owner or account loses access.

Complete the flow

  1. Check GET /status for connectivity and permissions.
  2. Send PUT /participants with fullName, email, locale and optional externalId. Save participant.id. Matching email updates the existing client in your account. Archived clients are rejected; changing an email creates a different client.
  3. Send POST /assessments with participantId, locale and expiresAt, plus a unique Idempotency-Key header. Expiry must be in the future, within 180 days. Save assessment.id.
  4. Fetch GET /assessments/{assessmentId}/questions. Render the returned text and choices in order. There are 120 questions, available in English, Arabic or Spanish.
  5. Save actual responses with PUT /assessments/{assessmentId}/answers. The body is an answers array of objects with questionId and integer value from 1 to 5. Send 1–120 unique question IDs per request. The API checks the IDs and upserts answers; it does not accept invented questions.
  6. Once all answers are saved, send POST /assessments/{assessmentId}/complete with an empty JSON object. Save result.id as the assessment result ID. GET /assessments/{assessmentId} also returns that ID after completion.
  7. Check GET /credits, then send POST /reports with assessmentResultId and a separate Idempotency-Key. Save report.id. A new permanent report consumes 1 credit. Assessment creation and completion are free.
  8. Read GET /reports/{reportId}. Add ?locale=en, ?locale=ar or ?locale=es for a localized view. Reading is free and does not change the saved language. The response uses the same approved report content and presentation as the owner dashboard; there is no fixed metric-count promise.

The assessment endpoints manage sessions created by this API. Report reads may access all full reports entitled to the account, including those created in the normal Portal workflow.

Retry without duplicate charges

Use an Idempotency-Key of 8–128 letters, digits, colons, underscores or hyphens. Reuse the same key and body after a failed assessment/report creation request. A different operation needs its own key. A changed body under the same key returns 409. Save your request IDs alongside the returned client, assessment, result and report IDs.

Repeating completion returns the saved result. Asking for a report that already exists returns that report without another charge, even with a new request ID. If generation fails, the normal credit reservation is released. Resolve the error and retry with the original ID. A failed response may follow a successful save, so do not assume every retry needs a new ID.

An incomplete assessment returns 409; missing credits return 402; an expired assessment returns 410. Missing or foreign-account records return 404. Invalid or revoked keys return 401; insufficient permissions return 403. JSON request bodies must not exceed 32 KiB. Unexpected input fields are rejected. All responses use Cache-Control: no-store.

Where the data goes

Clients and reports appear in the normal workspace; credit spending appears on the Credits page. Names and emails use the existing client record. externalId is your account-scoped integration reference: omitted values preserve the existing reference; supplied values may update it. It is deliberately omitted from recipient reports, emails and PDFs. Assessment locale controls the questionnaire and original report language; a read-time locale only changes the returned view.

This flow sends no invitation/report emails and creates no public sharing link. Sharing remains a separate owner action. Do not use API completion to bypass the invitation or automatic-delivery workflow.

Examples and downloads

The Developer page shows copyable Bash/cURL examples. Set PORTAL_API_BASE, PORTAL_API_KEY, each returned ID, the expiry timestamp and separate creation request IDs before continuing. Provide an answers.json file containing actual participant responses.

Import the Postman collection and configure baseUrl (including /partner/v1) and apiKey locally. Set expiresAt and answersJson; the collection captures returned IDs and initializes missing request IDs. Keep IDs for retries, and clear them when starting a new assessment/report. Running the report-generation request spends a credit. Do not share exports containing your secret or client data.

See the API reference (English) and OpenAPI specification for request and response fields. Older provider-based API references describe a different contract and do not apply to current Portal accounts.