> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/endpoints/search-people-auto-suggestion
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# People auto-suggestion

> Complete a skill as someone types, for free, to build a people search box in your own product.

- Endpoint: `POST https://api.reversecontact.com/v2/search/people/auto-suggestion`
- Credits: Free.
- Answer: synchronous.
- Available in: REST API, TypeScript and Python SDKs.
- Last verified: 2026-11-03

## Introduction

The People Auto-suggestion endpoint returns the skills that start with what someone has typed, most common first. It returns values only, never a profile.

It is made for products: use it to offer auto-suggestion in a search box of your own interface, then send the value your user picks to the `skills` filter of [People search](https://docs.reversecontact.com/endpoints/search-people#skills) or of its [free count](https://docs.reversecontact.com/endpoints/search-people-count).

This endpoint **costs 0 credits** and has its own rate limit: 1,000 calls per minute per workspace, or 500 on the free trial. Its calls never use up your workspace's [requests per minute](https://docs.reversecontact.com/guides/rate-limits).

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Request body

| Name    | Type   | Required | Description                                                                      |
| ------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `field` | string | Yes      | The filter to complete. `skills` is the only value today                         |
| `query` | string | Yes      | What has been typed so far, 1 to 100 characters. Case and accents are ignored    |
| `limit` | number | No       | Maximum values returned, from 1 to 25. Defaults to 10                            |

A value matches when it starts with `query`, spaces included: `machine l` returns `machine learning`, and `script` returns `scripting` but not `javascript`.

Any other `field`, an empty `query` or a `limit` out of range returns HTTP `422` and names the expected value.

## Response structure

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | `true` if the request was processed successfully |
| `error`   | `null`  | Always `null` on success                         |

**data** (SearchAutoSuggestion): Values that start with the query

| Field         | Type     | Description                                                              |
| ------------- | -------- | ------------------------------------------------------------------------ |
| `object`      | string   | Always `search_auto_suggestions`                                         |
| `entity`      | string   | Always `person`                                                          |
| `field`       | string   | The filter completed                                                     |
| `suggestions` | object[] | The values, most common first. Empty when no value starts with the query |

**suggestions[]** (AutoSuggestionValue): One value

| Field   | Type   | Description                                                       |
| ------- | ------ | ----------------------------------------------------------------- |
| `value` | string | The value to show, and to send as it is in the `skills` filter    |

Values come in lowercase and without accents, as they are held for matching. The `skills` filter ignores case, so you can restyle a value for display and still send it.

## Build a search box

A few habits keep the box fast and within its limit:

- **Call from your server.** The call needs your API key, which must never reach a browser.
- **Wait for a pause in the typing.** Calling about 200 ms after the last key sends one request for a burst of keys.
- **Start at two characters.** One letter matches too much to help.
- **Cancel the previous request** when a new one starts, so a late answer never replaces a newer one.
- **Keep the answers** for the session: the same prefix returns the same values.
- **Let people add what they typed.** An empty list only means that no value starts this way, so a person can still search on their own wording.
- **Treat a `429` like an empty list.** The call returns `429` with the code `RATE_LIMIT_EXCEEDED` past its limit, and also at times of very high demand, with a `Retry-After` header. Show no list, keep accepting what the person types, and try again on the next key.

## Code examples

**Code Examples**

```bash [cURL]
curl -X POST https://api.reversecontact.com/v2/search/people/auto-suggestion \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "skills",
    "query": "pyth",
    "limit": 5
  }'
```
```typescript [TypeScript SDK]
import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const result = await client.search.peopleAutoSuggestion({
  field: "skills",
  query: "pyth",
  limit: 5
});
console.log(result.data.suggestions?.map((suggestion) => suggestion.value));
```
```python [Python SDK]
import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    result = client.search.people_auto_suggestion(
        field="skills",
        query="pyth",
        limit=5,
    )
    if result.data is not None and result.data.suggestions is not None:
        print([suggestion.value for suggestion in result.data.suggestions])
```

## Example response

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": {
    "object": "search_auto_suggestions",
    "entity": "person",
    "field": "skills",
    "suggestions": [
      { "value": "python programming language" },
      { "value": "python" },
      { "value": "python langage de programmation" },
      { "value": "python programmiersprache" }
    ]
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "req_a1u2t3o4",
    "executionTimeMs": 170
  }
}
```