# White-label & branding

> The three modes of FCRA Partner Access, what the consumer sees in each, where your name, logo and colour appear, where the agency is named, and how to set your branding.

- **HTML:** https://offendersearch.app/docs/fcra/white-label
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed; see https://offendersearch.app/docs/fcra/sandbox.md
- **Authentication:** `X-API-Key` request header, on an account with FCRA Partner Access
- **FCRA API reference as markdown:** https://offendersearch.app/docs/fcra.md

## Three modes, one engine

Every FCRA partner runs on the same orders, controls, evidence, signed reports, disputes and consumer portal. The mode on your agreement decides who the consumer reporting agency is and therefore who runs the consumer-facing steps.

| Mode | You are | The consumer reporting agency is | Who runs consent, notices and the portal |
| --- | --- | --- | --- |
| `direct` | An employer, landlord or organization screening for itself | Us | We do, in your branding |
| `platform` | A platform, staffing firm or property manager screening for its clients | Us | We do, in your branding; each client is an end user you register |
| `cra` | A consumer reporting agency | You | You do, in your own flow; we furnish the records, controls, evidence and the dispute channel |

You choose the mode on the application (dashboard → FCRA → Settings, or `POST /v1/fcra/application`); the agreement fixes it. `GET /v1/fcra/partner` reports it as `kind`.

## What the consumer sees, surface by surface

In `direct` and `platform` mode the consumer sees you as the requester and sees the agency where the Fair Credit Reporting Act requires the consumer reporting agency to be identified. That is the whole of the white-label rule: your brand up front, the agency’s legal name where the law puts it.

| Surface | Your brand | The agency’s legal name |
| --- | --- | --- |
| Invitation e-mail and reminder | Sender name, header logo, button colour, reply-to | Footer: who prepares the report, consumer contact |
| Hosted consent page (`/apply/…`) | Logo or name at the top, button colour, “[Your name] has asked for your authorization” | Named in the disclosure and the authorization as the agency; the page footer |
| Disclosure and authorization texts | “[End user] may obtain a consumer report about you…” | “The report will be prepared by [agency]…” with the consumer contact |
| Copy of the report e-mail | Sender name, header, colour | Footer, and the portal it links to |
| Consumer portal | Your logo or name at the top; “Requested by [your name]” | “Prepared by [agency], a consumer reporting agency” with the dispute contact |
| Pre- and post-adverse notices | Sender name, header, colour; “[End user] is considering a decision…” | Named as the agency that prepared the report, with address and contact, as § 1681m requires |
| The report PDF and receipt | Your end user and reference on the report | The agency as the furnisher; the signed receipt |

- Links go to `offendersearch.app/apply/…` and the portal at `offendersearch.app/consumer/report`. A custom domain for those pages is not available yet.
- Want the consent step inside your own product? Create the invitation with `sendEmail: false` and present `applyUrl` yourself; the page still carries your branding.
- Platform partners: register each client as an end user. Its name is what the consumer reads as the requester in the disclosure; your branding frames the page.

## Set your branding

From the dashboard: FCRA → Settings → Branding (account admins). From the API: `PUT /v1/fcra/branding` with any of the fields below; what you send replaces what is stored. Our team seeds `displayName` and `website` from your application when it is approved.

PUT /v1/fcra/branding

```bash
curl -X PUT "https://api.offendersearch.app/v1/fcra/branding" \
  -H "X-API-Key: $OFFENDERSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Staffing",
    "logoUrl": "https://acme.example/logo.png",
    "primaryColor": "#0f766e",
    "supportEmail": "screening@acme.example",
    "website": "https://acme.example",
    "replyTo": "screening@acme.example"
  }'
```

| Field | Where it shows | Notes |
| --- | --- | --- |
| `displayName` | E-mail sender name, page header, portal, “Requested by” | Up to 120 characters |
| `logoUrl` | E-mail header, consent page header, portal header | An https URL to a PNG, JPEG or SVG; rendered up to 48 px tall on a white background, so a horizontal logo works best |
| `primaryColor` | Buttons and highlights on the consent page and in e-mails | `#rrggbb` |
| `supportEmail`, `supportPhone` | Where the consumer can reach you about the request itself (not about the report) | The pre-adverse notice tells the consumer to respond to you here |
| `website` | Linked from your name | https |
| `replyTo` | Reply-to on every e-mail we send on your behalf | Defaults to `supportEmail` |

## Set your branding — PUT /v1/fcra/branding

`PUT /v1/fcra/branding` · auth: `X-API-Key`

Replaces your branding. From the dashboard, an account admin only.

### Request

**Body** (application/json)

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `displayName` | `string` or null | optional | The name the consumer sees as the requester. Example `"Acme Staffing"`. |
| `logoUrl` | `string` or null | optional | An https logo shown at the top of the hosted flow and e-mails. |
| `primaryColor` | `string` or null | optional | A hex colour for buttons and highlights. Example `"#0f766e"`. |
| `supportEmail` | `string` or null | optional | Where the consumer can reach you about the request itself. |
| `supportPhone` | `string` or null | optional | A phone number to show consumers. `null` clears it. |
| `website` | `string` or null | optional | Your public website (`https://…`). `null` clears it. |
| `replyTo` | `string` or null | optional | The reply-to address on e-mails we send on your behalf. |

### Response

**200** (application/json) — 

The body is [the `BrandingStatus` object](https://offendersearch.app/docs/fcra/white-label#object-brandingstatus). Your branding, your partner kind, and the agency named on every disclosure.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 403 | — | A non-admin seat on a dashboard session (string `detail`). |
| 422 | — | A colour that is not `#rrggbb`, or a URL that is not https. |

## The BrandingStatus object

Your branding, your partner kind, and the agency named on every disclosure.

Returned or accepted by [`GET /v1/fcra/branding`](https://offendersearch.app/docs/fcra/white-label#reference-get-v1-fcra-branding), [`PUT /v1/fcra/branding`](https://offendersearch.app/docs/fcra/white-label#reference-put-v1-fcra-branding).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `branding` | [Branding](https://offendersearch.app/docs/fcra/white-label#object-branding) |  | As stored (empty when none). |
| `kind` | `string` — one of `"cra"`, `"direct"`, `"platform"` |  | `cra` (you are the CRA), `direct` (we are the CRA; you are the end user) or `platform` (we are the CRA; you order for your clients under your brand). |
| `agency` | [Agency](https://offendersearch.app/docs/fcra/hosted-consent#object-agency) |  | The consumer reporting agency named on every disclosure, report and notice. |

## The Branding object — how the consumer sees you

Your branding on the hosted consent flow, the e-mails and the portal header.

Returned or accepted by [`GET /v1/fcra/partner`](https://offendersearch.app/docs/fcra/access#reference-get-v1-fcra-partner), [`GET /v1/consumer/portal/report`](https://offendersearch.app/docs/fcra/consumer-portal#reference-get-v1-consumer-portal-report), [`GET /v1/fcra/branding`](https://offendersearch.app/docs/fcra/white-label#reference-get-v1-fcra-branding), [`PUT /v1/fcra/branding`](https://offendersearch.app/docs/fcra/white-label#reference-put-v1-fcra-branding), [`GET /v1/apply/{token}`](https://offendersearch.app/docs/fcra/hosted-consent#reference-get-v1-apply-token).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `displayName` | `string` or null |  | The name the consumer sees as the requester. Example `"Acme Staffing"`. |
| `logoUrl` | `string` or null |  | An https logo shown at the top of the hosted flow and e-mails. |
| `primaryColor` | `string` or null |  | A hex colour for buttons and highlights. Example `"#0f766e"`. |
| `supportEmail` | `string` or null |  | Where the consumer can reach you about the request itself. |
| `supportPhone` | `string` or null |  | A phone number shown to consumers on the hosted consent page and in notices. `null` to show none. |
| `website` | `string` or null |  | Your public website, linked from the hosted consent page and the consumer portal. `null` for none. |
| `replyTo` | `string` or null |  | The reply-to address on e-mails we send on your behalf. |

## Your branding — GET /v1/fcra/branding

`GET /v1/fcra/branding` · auth: `X-API-Key`



### Request

### Response

**200** (application/json) — 

The body is [the `BrandingStatus` object](https://offendersearch.app/docs/fcra/white-label#object-brandingstatus). Your branding, your partner kind, and the agency named on every disclosure.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |

## Preview it

On a sandbox key every account is a `direct` partner: set the branding, create an invitation with `sendEmail: false`, and open `applyUrl` to see the consent page exactly as a consumer would, in your colours, with the agency named in the disclosure. The sandbox sends no e-mail; the notices list shows what would have gone.

---

## Related

- Previous: [FCRA API sandbox & test subjects](https://offendersearch.app/docs/fcra/sandbox.md)
- Next: [Orders](https://offendersearch.app/docs/fcra/orders.md)
- Index: [FCRA API reference](https://offendersearch.app/docs/fcra.md)