Create a person

curl --request POST \
  --url https://api.metal.ai/v1/people \
  --header 'Content-Type: application/json' \
  --header 'x-metal-api-key: <api-key>' \
  --header 'x-metal-client-id: <api-key>' \
  --data '
{
  "firstName": "Jordan",
  "lastName": "Rivera",
  "email": "jordan@example.com",
  "currentTitle": "<string>",
  "currentCompanyName": "<string>",
  "company": "<string>",
  "linkedinUrl": "<string>",
  "phoneNumber": "<string>",
  "location": {
    "city": "<string>",
    "state": "<string>",
    "country": "<string>"
  },
  "externalId": "<string>"
}
'

import requests

url = "https://api.metal.ai/v1/people"

payload = {
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan@example.com",
    "currentTitle": "<string>",
    "currentCompanyName": "<string>",
    "company": "<string>",
    "linkedinUrl": "<string>",
    "phoneNumber": "<string>",
    "location": {
        "city": "<string>",
        "state": "<string>",
        "country": "<string>"
    },
    "externalId": "<string>"
}
headers = {
    "x-metal-client-id": "<api-key>",
    "x-metal-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-metal-client-id': '<api-key>',
    'x-metal-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'Jordan',
    lastName: 'Rivera',
    email: 'jordan@example.com',
    currentTitle: '<string>',
    currentCompanyName: '<string>',
    company: '<string>',
    linkedinUrl: '<string>',
    phoneNumber: '<string>',
    location: {city: '<string>', state: '<string>', country: '<string>'},
    externalId: '<string>'
  })
};

fetch('https://api.metal.ai/v1/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.metal.ai/v1/people"

	payload := strings.NewReader("{\n  \"firstName\": \"Jordan\",\n  \"lastName\": \"Rivera\",\n  \"email\": \"jordan@example.com\",\n  \"currentTitle\": \"<string>\",\n  \"currentCompanyName\": \"<string>\",\n  \"company\": \"<string>\",\n  \"linkedinUrl\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"location\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"externalId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-metal-client-id", "<api-key>")
	req.Header.Add("x-metal-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "id": "665f1c2a9b1e4a0012a3b4c5",
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan@example.com",
    "currentTitle": "Chief Executive Officer",
    "currentCompanyName": "<string>",
    "company": "<string>",
    "linkedinUrl": "<string>",
    "phoneNumber": "<string>",
    "location": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>"
    },
    "externalId": "<string>",
    "externalReference": {
      "source": "<string>",
      "id": "<string>"
    },
    "enrichment": {
      "subsector": [
        {
          "value": "Self-Funded Health Insurance / Third Party Administrator (TPA)",
          "source": "CIM",
          "confidence": 100,
          "pinned": true,
          "discoveredAt": "2026-02-14T10:00:00Z"
        },
        {
          "value": "Third-Party Administrators (TPAs)",
          "source": "Market Report",
          "confidence": 57,
          "pinned": false,
          "discoveredAt": "2026-01-20T10:00:00Z"
        }
      ]
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "reused": true
  }
}

{
  "error": "Invalid request body"
}

{
  "error": "invalid api key or clientId"
}

Create a person

Creates a person. Provide at least a name; link to a company with company.

Email matching. If the request includes an email, Metal checks it against the email and personal email of the contacts Metal can match — people created in Metal or synced from a connected CRM — before creating anything. The comparison ignores case.

One eligible match: Metal creates no new person. The response returns the existing person with reused: true. Metal may fill empty fields on that person, such as currentTitle or linkedinUrl, with values from your request. Fields that already have values are not overwritten. A person synced from your CRM is returned unchanged.
Several matches: If more than one match is eligible, Metal creates the new person but holds it for duplicate review. A held person is not written to your CRM until that review is resolved.
No match, or only ineligible matches: Metal creates the person as usual.

An existing person with the same external reference always takes precedence over an email match.

The response status is 201 in every case. reused: true means the request matched an existing person by email and Metal returned that person. A create that matches an existing external reference also returns that person, with reused omitted, so an absent reused does not prove a new person was created.

POST

people

Create a person

curl --request POST \
  --url https://api.metal.ai/v1/people \
  --header 'Content-Type: application/json' \
  --header 'x-metal-api-key: <api-key>' \
  --header 'x-metal-client-id: <api-key>' \
  --data '
{
  "firstName": "Jordan",
  "lastName": "Rivera",
  "email": "jordan@example.com",
  "currentTitle": "<string>",
  "currentCompanyName": "<string>",
  "company": "<string>",
  "linkedinUrl": "<string>",
  "phoneNumber": "<string>",
  "location": {
    "city": "<string>",
    "state": "<string>",
    "country": "<string>"
  },
  "externalId": "<string>"
}
'

import requests

url = "https://api.metal.ai/v1/people"

payload = {
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan@example.com",
    "currentTitle": "<string>",
    "currentCompanyName": "<string>",
    "company": "<string>",
    "linkedinUrl": "<string>",
    "phoneNumber": "<string>",
    "location": {
        "city": "<string>",
        "state": "<string>",
        "country": "<string>"
    },
    "externalId": "<string>"
}
headers = {
    "x-metal-client-id": "<api-key>",
    "x-metal-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-metal-client-id': '<api-key>',
    'x-metal-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'Jordan',
    lastName: 'Rivera',
    email: 'jordan@example.com',
    currentTitle: '<string>',
    currentCompanyName: '<string>',
    company: '<string>',
    linkedinUrl: '<string>',
    phoneNumber: '<string>',
    location: {city: '<string>', state: '<string>', country: '<string>'},
    externalId: '<string>'
  })
};

fetch('https://api.metal.ai/v1/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.metal.ai/v1/people"

	payload := strings.NewReader("{\n  \"firstName\": \"Jordan\",\n  \"lastName\": \"Rivera\",\n  \"email\": \"jordan@example.com\",\n  \"currentTitle\": \"<string>\",\n  \"currentCompanyName\": \"<string>\",\n  \"company\": \"<string>\",\n  \"linkedinUrl\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"location\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"externalId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-metal-client-id", "<api-key>")
	req.Header.Add("x-metal-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "id": "665f1c2a9b1e4a0012a3b4c5",
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan@example.com",
    "currentTitle": "Chief Executive Officer",
    "currentCompanyName": "<string>",
    "company": "<string>",
    "linkedinUrl": "<string>",
    "phoneNumber": "<string>",
    "location": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>"
    },
    "externalId": "<string>",
    "externalReference": {
      "source": "<string>",
      "id": "<string>"
    },
    "enrichment": {
      "subsector": [
        {
          "value": "Self-Funded Health Insurance / Third Party Administrator (TPA)",
          "source": "CIM",
          "confidence": 100,
          "pinned": true,
          "discoveredAt": "2026-02-14T10:00:00Z"
        },
        {
          "value": "Third-Party Administrators (TPAs)",
          "source": "Market Report",
          "confidence": 57,
          "pinned": false,
          "discoveredAt": "2026-01-20T10:00:00Z"
        }
      ]
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "reused": true
  }
}

{
  "error": "Invalid request body"
}

{
  "error": "invalid api key or clientId"
}

Authorizations

x-metal-client-id

string

header

default:<client-id>

required

The Client ID of your API key.

x-metal-api-key

string

header

default:<api-key>

required

The secret value of your API key.

Body

application/json

firstName

string

required

Example:

"Jordan"

lastName

string

required

Example:

"Rivera"

string

Example:

"jordan@example.com"

currentTitle

string

currentCompanyName

string

company

string

The id of the company to link this person to.

linkedinUrl

string

phoneNumber

string

location

object

Show child attributes

externalId

string

Response

The created person, or the existing person Metal returned.

data

object

A person returned by POST /v1/people. Adds reused to the standard person.

Show child attributes

Overview

Core records

Enrichment & scoring

Lists & taxonomy

Workflows & automation

Inference

Data

Administration

Create a person

Authorizations

Body

Response