---
title: "Create Research"
method: POST
path: "/v1/research"
---

# Create Research

`POST /v1/research`

Start a new person research request.

Include as many details as possible about the person in the description field
(full name, company, title, location, social media handles, etc.) for best results.

Requires sufficient credits. Returns 402 Payment Required if not enough credits.
Returns 429 Too Many Requests if you have 10 or more research requests currently running.

## Request body

- ResearchRequestV1
  - `description` string, required — Description of the person to research

## Response `200`

Successful Response

- CreateResearchResponseV1 — Response from POST /v1/research - creating a new research request.
  - `id` string, required — Unique identifier for the research job
  - `url` string, required — URL to view the research profile on Happenstance
  - `warning` string, nullable — Warning message when credit balance is low

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `404` — Not Found
- `410` — Gone
- `422` — Validation Error
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/happenstance/apis/happenstance-api.md) · [All operations](https://skmtc.net/happenstance/apis/happenstance-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/happenstance/happenstance-api/versions/d5e1f45dc5e4/schema)