# Suggest a registration from a website

Source: https://joinsimplesms.com/docs/api/registrations/prefill
Index: https://joinsimplesms.com/llms.txt

`POST /v1/registrations/prefill`

Reads the public pages of the website (homepage plus the sign-up, contact, privacy and terms pages it links to) and returns suggestions for a registration: business name, legal name when the site states one, use case, description, opt-in / privacy / terms URLs with ranked candidates, support email, contact phone, address and industry. Creates and files nothing. EIN and entity type are never suggested. Names, contact details and URLs are read with fixed rules; where AI drafting is available (ai: true) a third-party AI model drafts the description, use case, industry and three starter example messages from the same public page text, and every field it returns is validated. Review the fields, then send them to POST /registrations (drafted examples as starter_messages, or as sample_messages once they are yours). One read per website per account every 10 minutes; 10 websites a minute.

Send your API key as a bearer token: `Authorization: Bearer ssms_sk_...`. Test keys run this endpoint against the [sandbox](/docs/sandbox); see [Authentication](/docs/authentication) for key modes and scopes.

## Request body

JSON (`Content-Type: application/json`).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `website` | string (uri) | Yes | Example: `https://acmeplumbing.com`. |

## Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Suggestions (reachable: false when the site could not be read) | `RegistrationPrefill` |
| 400 | Invalid website | `Error` |
| 401 | Missing, malformed, or revoked API key | `Error` |
| 402 | Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged | `Error` |
| 429 | Rate limit or quota exceeded | `Error` |

### 200: `RegistrationPrefill` fields

| Field | Type | Description |
| --- | --- | --- |
| `object` | `registration_prefill` |  |
| `reachable` | boolean | false = the website could not be read; fields then holds only the website |
| `error` | string | Why the site could not be read Nullable. |
| `fields` | object | Suggestions, shaped like RegistrationInput. Only fields we found are present. |
| `fields.website` | string (uri) |  |
| `fields.business_name` | string |  |
| `fields.use_case` | string |  |
| `fields.description` | string | At most 500 characters. |
| `fields.opt_in_url` | string (uri) |  |
| `fields.privacy_url` | string (uri) |  |
| `fields.terms_url` | string (uri) |  |
| `fields.support_email` | string (email) |  |
| `fields.sample_messages` | array of string | Starter drafts written for this business (AI drafting only). Send them as starter_messages. |
| `fields.brand` | object | Never includes ein or entity_type. |
| `fields.brand.legal_name` | string |  |
| `fields.brand.street` | string |  |
| `fields.brand.city` | string |  |
| `fields.brand.state` | string |  |
| `fields.brand.postal_code` | string |  |
| `fields.brand.country` | string |  |
| `fields.brand.vertical` | `PROFESSIONAL`, `REAL_ESTATE`, `HEALTHCARE`, `HUMAN_RESOURCES`, `ENERGY`, `ENTERTAINMENT`, `RETAIL`, `TRANSPORTATION`, `AGRICULTURE`, `INSURANCE`, `POSTAL`, `EDUCATION`, `HOSPITALITY`, `FINANCIAL`, `LEGAL`, `CONSTRUCTION`, `NGO`, `MANUFACTURING`, `GOVERNMENT`, `TECHNOLOGY`, `COMMUNICATION` |  |
| `fields.brand.contact_email` | string |  |
| `fields.brand.contact_phone` | string |  |
| `suggested` | array of string | Dotted names of every field filled in, e.g. business_name, brand.city |
| `sources` | object | Where each suggested field came from: page = read from your pages by fixed rules; ai = drafted or chosen by an AI model |
| `candidates` | object | Pages that could be the opt-in, privacy policy and terms, best first |
| `candidates.opt_in` | array of object |  |
| `candidates.opt_in[].url` | string (uri) |  |
| `candidates.opt_in[].confidence` | number | Maximum 1. Minimum 0. |
| `candidates.opt_in[].reason` | string |  |
| `candidates.privacy` | array of object |  |
| `candidates.privacy[].url` | string (uri) |  |
| `candidates.privacy[].confidence` | number | Maximum 1. Minimum 0. |
| `candidates.privacy[].reason` | string |  |
| `candidates.terms` | array of object |  |
| `candidates.terms[].url` | string (uri) |  |
| `candidates.terms[].confidence` | number | Maximum 1. Minimum 0. |
| `candidates.terms[].reason` | string |  |
| `about` | string | What the site says the business is (its meta description) Nullable. |
| `ai` | boolean | true when an AI model drafted any of these suggestions |

## Errors

| Status | When |
| --- | --- |
| 400 | Invalid website |
| 401 | Missing, malformed, or revoked API key |
| 402 | Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged |
| 429 | Rate limit or quota exceeded |

Every error has the same JSON shape, and `request_id` matches the `X-Request-Id` response header. [Errors](/docs/errors) lists every code and what to do about it.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "What went wrong, in plain words.",
    "param": "the_field",
    "request_id": "req_a1B2c3D4e5F6g7H8"
  }
}
```

## Examples

### curl

```bash
curl -X POST "https://api.joinsimplesms.com/v1/registrations/prefill" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "website": "https://acmeplumbing.com"
}'
```

### Node.js

The Node.js SDK does not wrap this endpoint yet; call it with `fetch`.

```javascript
const res = await fetch('https://api.joinsimplesms.com/v1/registrations/prefill', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLESMS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "website": "https://acmeplumbing.com"
  }),
});

if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
```

### Python

The Python SDK does not wrap this endpoint yet; call it over HTTP.

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://api.joinsimplesms.com/v1/registrations/prefill",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['SIMPLESMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "website": "https://acmeplumbing.com"
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    data = json.load(res)
```

## Related

- Guide: [Compliance & registration](/docs/compliance)
- [All registrations endpoints](/docs/api#registrations)
- [API reference](/docs/api)