curl --request POST \
  --url https://api.goldilocksai.app/enrichment/profiles \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "people_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "enrichment_type": "email"
}
'

{
  "success": true,
  "data": {
    "profiles": [
      {
        "people_id": "123e4567-e89b-12d3-a456-426614174000",
        "email": [
          {
            "email": "john.doe@example.com",
            "priority": 1
          }
        ]
      }
    ]
  },
  "metadata": {
    "results": {
      "total_profiles_requested_enrichment": 2,
      "total_profiles_enriched": 1,
      "warnings": [
        {
          "people_id": "123e4567-e89b-12d3-a456-426614174001",
          "type": "W0001_ENRICHMENT_UNAVAILABLE_TYPE",
          "enrichment_type": "email",
          "reason": "Profile does not have email data"
        }
      ]
    }
  },
  "error": null,
  "request_id": "abc12345-e89b-12d3-a456-426614174000",
  "processing_time_ms": 250
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Your request contains invalid data. Please check your input and try again.",
    "details": {
      "field": "query",
      "error": "Field is required"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 50
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 20
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied. You don't have permission to access this resource."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 30
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "One or more requested profiles were not found",
    "details": {
      "not_found_ids": [
        "999e4567-e89b-12d3-a456-426614174999"
      ]
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 60
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making another request."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 10
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 100
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "BAD_GATEWAY",
    "message": "External service error. Please try again later."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 5000
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable. Please retry your request."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 200
}

Endpoints

Enrichment

Enrich existing profiles with additional contact information or professional achievements. This endpoint adds valuable data to profiles you’ve found through searches, such as email addresses, phone numbers, awards, publications, memberships, or patents. You can enrich up to 50 profiles per request, and each request focuses on one enrichment type. The endpoint validates profile existence before processing and returns warnings if enrichment data is unavailable for specific profiles.

POST

enrichment

profiles

curl --request POST \
  --url https://api.goldilocksai.app/enrichment/profiles \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "people_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "enrichment_type": "email"
}
'

{
  "success": true,
  "data": {
    "profiles": [
      {
        "people_id": "123e4567-e89b-12d3-a456-426614174000",
        "email": [
          {
            "email": "john.doe@example.com",
            "priority": 1
          }
        ]
      }
    ]
  },
  "metadata": {
    "results": {
      "total_profiles_requested_enrichment": 2,
      "total_profiles_enriched": 1,
      "warnings": [
        {
          "people_id": "123e4567-e89b-12d3-a456-426614174001",
          "type": "W0001_ENRICHMENT_UNAVAILABLE_TYPE",
          "enrichment_type": "email",
          "reason": "Profile does not have email data"
        }
      ]
    }
  },
  "error": null,
  "request_id": "abc12345-e89b-12d3-a456-426614174000",
  "processing_time_ms": 250
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Your request contains invalid data. Please check your input and try again.",
    "details": {
      "field": "query",
      "error": "Field is required"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 50
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 20
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied. You don't have permission to access this resource."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 30
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "One or more requested profiles were not found",
    "details": {
      "not_found_ids": [
        "999e4567-e89b-12d3-a456-426614174999"
      ]
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 60
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making another request."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 10
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 100
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "BAD_GATEWAY",
    "message": "External service error. Please try again later."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 5000
}

{
  "success": false,
  "data": null,
  "metadata": null,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable. Please retry your request."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing_time_ms": 200
}

Authorizations

X-API-Key

string

header

required

API key for authentication. Obtain your API key via the web application.

Body

application/json

Request body for enriching profiles

people_ids

string<uuid>[]

required

List of people IDs to enrich (max 50 per request)

Required array length: 1 - 50 elements

UUID v4 identifier

Example:

[
  "123e4567-e89b-12d3-a456-426614174000",
  "123e4567-e89b-12d3-a456-426614174001"
]

enrichment_type

enum<string>

required

Type of enrichment data to retrieve

Available options:

email,

phone,

award,

publication,

membership,

patent

Response

Enrichment completed successfully

success

boolean

required

request_id

string<uuid>

required

processing_time_ms

integer

required

data

object

Response data for POST /enrichment/profiles. Metadata is returned at the envelope level, not nested here.

Show child attributes

metadata

object

Metadata for POST /enrichment/profiles

Show child attributes

error

null