> ## Documentation Index
> Fetch the complete documentation index at: https://testdocs.clodura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich and Clean Individual Contact Records via API

> Enrich a single contact record with verified professional details — title, seniority, location, and company data — using name, email, or LinkedIn URL.

The Enrich Contacts endpoint takes minimal identifying information about a person and returns a complete, cleaned professional profile pulled from Clodura's database. You can use this endpoint to fill in missing CRM fields, standardize contact records, and add firmographic context (such as industry, revenue, and employee count) to your existing contact lists — all without manual research.

Clodura matches contacts based on the identifiers you supply. The more specific the input, the higher the match confidence. For example, providing a `linkedinUrl` produces the most accurate results, while passing only a name with an organization name has lower confidence and may return a `200` with no enriched data if no match is found.

<Note>
  **Credit cost:**

  * **1 credit** when only organization-level details are returned.
  * **2 credits** when a full person enrichment is completed by Clodura.

  No credits are charged if Clodura cannot find any matching information.
</Note>

## Endpoint

`POST /api/v1/cleanup/enrich`

## Request

### Headers

| Header         | Value                |
| -------------- | -------------------- |
| `X-API-KEY`    | Your Clodura API key |
| `Content-Type` | `application/json`   |

### Body Parameters

At least one identifier must be provided. Using a combination of fields increases match accuracy.

<ParamField body="linkedinUrl" type="string">
  The person's LinkedIn profile URL (e.g., `https://www.linkedin.com/in/kapilkhangaonkar/`). This is the highest-confidence identifier — use it whenever available.
</ParamField>

<ParamField body="email" type="string">
  The person's email address (e.g., `john@example.com`). Produces medium-confidence matches, especially when combined with `firstName` and `lastName`.
</ParamField>

<ParamField body="firstName" type="string">
  The person's first name. Use in combination with `lastName` and at least one company identifier.
</ParamField>

<ParamField body="lastName" type="string">
  The person's last name. Use in combination with `firstName` and at least one company identifier.
</ParamField>

<ParamField body="organisationName" type="string">
  The name of the person's employer. Use with `firstName` and `lastName` when no domain or LinkedIn URL is available. This produces the lowest-confidence match.
</ParamField>

<ParamField body="orgLinkedinUrl" type="string">
  The LinkedIn URL of the employer organization (e.g., `https://www.linkedin.com/company/clodura-ai/`). Combine with `firstName` and `lastName` for medium-confidence matching.
</ParamField>

### Recommended Identifier Combinations

| Input Combination                             | Match Confidence |
| --------------------------------------------- | ---------------- |
| `linkedinUrl`                                 | Highest          |
| `firstName` + `lastName` + `email`            | Medium           |
| `email` alone                                 | Medium           |
| `firstName` + `lastName` + `orgLinkedinUrl`   | Medium           |
| `firstName` + `lastName` + `organisationName` | Low              |

## Example Request

<CodeGroup>
  ```bash cURL — by LinkedIn URL theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/cleanup/enrich \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "linkedinUrl": "https://in.linkedin.com/in/dipak-bhoi-b3a700172"
    }'
  ```

  ```bash cURL — by name and email theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/cleanup/enrich \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "firstName": "Dipak",
      "lastName": "Bhoi",
      "email": "dipak@example.com"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.clodura.ai/api/v1/cleanup/enrich"

  headers = {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Highest confidence: LinkedIn URL
  payload = {
      "linkedinUrl": "https://in.linkedin.com/in/dipak-bhoi-b3a700172"
  }

  # Medium confidence: name + email
  # payload = {
  #     "firstName": "Dipak",
  #     "lastName": "Bhoi",
  #     "email": "dipak@example.com"
  # }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Response

A successful `200` response returns a fully enriched contact object along with credit usage details.

<ResponseField name="personId" type="string">
  Clodura's unique identifier for the matched person.
</ResponseField>

<ResponseField name="firstName" type="string">
  The person's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  The person's last name.
</ResponseField>

<ResponseField name="linkedinUrl" type="string">
  The person's LinkedIn profile URL.
</ResponseField>

<ResponseField name="personTitle" type="string">
  The person's current job title.
</ResponseField>

<ResponseField name="functional" type="array">
  Department or functional area (e.g., `Engineering`, `Sales`).
</ResponseField>

<ResponseField name="seniority" type="array">
  Seniority level (e.g., `Entry Level`, `Manager`, `Director`).
</ResponseField>

<ResponseField name="personCity" type="string">
  The person's current city.
</ResponseField>

<ResponseField name="personState" type="string">
  The person's current state.
</ResponseField>

<ResponseField name="personCountry" type="string">
  The person's current country.
</ResponseField>

<ResponseField name="organisation" type="object">
  <Expandable title="organisation fields">
    <ResponseField name="organisationId" type="string">
      Clodura's unique ID for the employer.
    </ResponseField>

    <ResponseField name="organisationName" type="string">
      Name of the employer organization.
    </ResponseField>

    <ResponseField name="domain" type="string">
      Primary domain of the employer.
    </ResponseField>

    <ResponseField name="orgLinkedinUrl" type="string">
      LinkedIn URL for the employer organization.
    </ResponseField>

    <ResponseField name="industry" type="string">
      Industry sector of the employer.
    </ResponseField>

    <ResponseField name="organisationEmployeeSize" type="string">
      Headcount range of the employer (e.g., `51 - 200`).
    </ResponseField>

    <ResponseField name="boardlineNumbers" type="string">
      Company switchboard or main phone number if available.
    </ResponseField>

    <ResponseField name="foundedYear" type="integer">
      Year the company was founded.
    </ResponseField>

    <ResponseField name="revenue" type="string">
      Estimated annual revenue bracket of the employer.
    </ResponseField>

    <ResponseField name="organisationCity" type="string">
      City of the employer's headquarters.
    </ResponseField>

    <ResponseField name="organisationState" type="string">
      State of the employer's headquarters.
    </ResponseField>

    <ResponseField name="organisationCountry" type="string">
      Country of the employer's headquarters.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="creditUsage" type="object">
  <Expandable title="creditUsage fields">
    <ResponseField name="creditsConsumed" type="integer">
      Number of credits deducted for this request (1 or 2).
    </ResponseField>

    <ResponseField name="remainingCredits" type="integer">
      Credits remaining in your account after this request.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "personId": "2796802024249754331",
  "firstName": "Dipak",
  "lastName": "Bhoi",
  "linkedinUrl": "https://in.linkedin.com/in/dipak-bhoi-b3a700172",
  "personTitle": "Software Engineer",
  "functional": ["Engineering"],
  "seniority": ["Entry Level"],
  "personCity": "Pune",
  "personCountry": "India",
  "personState": "Maharashtra",
  "organisation": {
    "organisationId": "2389402640191586304",
    "organisationName": "Clodura.AI",
    "domain": "clodura.ai",
    "orgLinkedinUrl": "https://www.linkedin.com/company/clodura-ai/",
    "industry": "Technology",
    "organisationEmployeeSize": "51 - 200",
    "boardlineNumbers": "+1-555-0100",
    "foundedYear": 2015,
    "revenue": "1M-10M",
    "organisationCity": "Pune",
    "organisationState": "Maharashtra",
    "organisationCountry": "India"
  },
  "creditUsage": {
    "creditsConsumed": 2,
    "remainingCredits": 3203
  }
}
```

## Error Codes

| Status | Meaning                                                                  |
| ------ | ------------------------------------------------------------------------ |
| `400`  | Bad request — contacts array limit exceeded or malformed input           |
| `401`  | Unauthorized — your API key is missing or invalid                        |
| `402`  | Payment required — credits exhausted; upgrade your plan or add credits   |
| `403`  | Forbidden — this endpoint requires a paid Clodura plan                   |
| `404`  | No match found — Clodura has no enrichment data for the provided contact |
| `409`  | Daily rate limit reached — maximum API calls for this endpoint exceeded  |
| `422`  | Unprocessable entity — invalid parameter combination or malformed JSON   |
| `429`  | Rate limit exceeded — reduce request frequency or upgrade your plan      |