{
  "info": {
    "name": "Elvesora Enrichment API",
    "description": "Ready-to-run v1 requests for credential verification, company enrichment, and idempotent retries. Response examples cover IDEMPOTENCY_KEY_CONFLICT (409), VALIDATION_ERROR (422), LIMIT_EXCEEDED (429), SERVICE_UNAVAILABLE (500 or 503), and upstream 5xx responses surfaced as UPSTREAM_ERROR.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://enrichment.elvesora.com/api/v1"
    },
    {
      "key": "api_key",
      "value": "YOUR_API_KEY"
    },
    {
      "key": "idempotency_key",
      "value": "enrich-acme-001"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "Verify API token",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}/account",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "account"
          ]
        },
        "description": "Verifies the bearer credential without consuming an enrichment credit. The response intentionally excludes team, user, token, subscription, and billing data."
      },
      "response": [
        {
          "name": "Credential active",
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "Cache-Control",
              "value": "no-store, private"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": true,\n  \"data\": {\n    \"credential_status\": \"active\",\n    \"product\": \"company_enrichment\",\n    \"api_version\": \"v1\"\n  }\n}"
        },
        {
          "name": "Unauthorized",
          "status": "Unauthorized",
          "code": 401,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"UNAUTHORIZED\",\n  \"message\": \"Unauthorized\"\n}"
        },
        {
          "name": "Too many credential checks",
          "status": "Too Many Requests",
          "code": 429,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"message\": \"Too Many Attempts.\"\n}"
        },
        {
          "name": "Credential store unavailable",
          "status": "Service Unavailable",
          "code": 503,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"SERVICE_UNAVAILABLE\",\n  \"message\": \"Service temporarily unavailable. Please try again later.\"\n}"
        }
      ]
    },
    {
      "name": "Enrich company",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{idempotency_key}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"domain\": \"acme.com\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/enrichment/company",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "enrichment",
            "company"
          ]
        },
        "description": "Successful ENRICHED responses consume one credit. The credits object and X-Credits-* headers are post-count. Local request validation returns VALIDATION_ERROR (422), an exhausted credit allowance returns LIMIT_EXCEEDED (429), a downstream connection or runtime failure returns SERVICE_UNAVAILABLE (500), and upstream 5xx statuses are preserved with result_type UPSTREAM_ERROR."
      },
      "response": [
        {
          "name": "Enriched",
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "1"
            }
          ],
          "body": "{\n  \"success\": true,\n  \"result_type\": \"ENRICHED\",\n  \"message\": \"Company enrichment completed successfully\",\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"domain\": \"acme.com\"\n  },\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 6,\n    \"remaining\": 94,\n    \"consumed_by_request\": 1,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 94,\n  \"limit\": 100\n}"
        },
        {
          "name": "Validation error",
          "status": "Unprocessable Entity",
          "code": 422,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"VALIDATION_ERROR\",\n  \"message\": \"Validation failed.\",\n  \"errors\": {\n    \"domain\": [\n      \"The domain field is required.\"\n    ]\n  }\n}"
        },
        {
          "name": "Credit limit exceeded",
          "status": "Too Many Requests",
          "code": 429,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"LIMIT_EXCEEDED\",\n  \"message\": \"Request limit exceeded. Please upgrade your plan.\",\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 100,\n    \"remaining\": 0,\n    \"consumed_by_request\": 0,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 0,\n  \"limit\": 100\n}"
        },
        {
          "name": "Service unavailable",
          "status": "Internal Server Error",
          "code": 500,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"SERVICE_UNAVAILABLE\",\n  \"message\": \"Service temporarily unavailable. Please try again later.\",\n  \"response_code\": 500,\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 6,\n    \"remaining\": 94,\n    \"consumed_by_request\": 0,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 94,\n  \"limit\": 100\n}"
        },
        {
          "name": "Upstream error",
          "status": "Bad Gateway",
          "code": 502,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"UPSTREAM_ERROR\",\n  \"message\": \"Enrichment request failed\",\n  \"response_code\": 502,\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 6,\n    \"remaining\": 94,\n    \"consumed_by_request\": 0,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 94,\n  \"limit\": 100\n}"
        }
      ]
    },
    {
      "name": "Replay same idempotency key",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{idempotency_key}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"domain\": \"acme.com\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/enrichment/company",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "enrichment",
            "company"
          ]
        },
        "description": "Responses are retained for 24 hours. Reusing the same key with the same domain returns Idempotency-Status: replayed and does not consume another credit. Reusing the key with a different domain within that window returns IDEMPOTENCY_KEY_CONFLICT (409). If the original request is still in progress beyond the bounded wait, the API returns SERVICE_UNAVAILABLE (503) without consuming a credit; retry with the same key."
      },
      "response": [
        {
          "name": "Idempotent replay",
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "Idempotency-Status",
              "value": "replayed"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": true,\n  \"result_type\": \"ENRICHED\",\n  \"message\": \"Company enrichment completed successfully\",\n  \"data\": {\n    \"company_name\": \"Acme Corporation\",\n    \"domain\": \"acme.com\"\n  },\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 6,\n    \"remaining\": 94,\n    \"consumed_by_request\": 0,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 94,\n  \"limit\": 100\n}"
        },
        {
          "name": "Idempotency key conflict",
          "status": "Conflict",
          "code": 409,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "Idempotency-Status",
              "value": "conflict"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"IDEMPOTENCY_KEY_CONFLICT\",\n  \"message\": \"This Idempotency-Key was already used with a different domain.\",\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 6,\n    \"remaining\": 94,\n    \"consumed_by_request\": 0,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 94,\n  \"limit\": 100\n}"
        },
        {
          "name": "Idempotency request still in progress",
          "status": "Service Unavailable",
          "code": 503,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Credits-Consumed",
              "value": "0"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"result_type\": \"SERVICE_UNAVAILABLE\",\n  \"message\": \"Service temporarily unavailable. Please try again later.\",\n  \"response_code\": 503,\n  \"credits\": {\n    \"limit\": 100,\n    \"used\": 6,\n    \"remaining\": 94,\n    \"consumed_by_request\": 0,\n    \"period_started_at\": \"2026-06-01\",\n    \"period_ends_at\": \"2026-07-01\"\n  },\n  \"remaining\": 94,\n  \"limit\": 100\n}"
        }
      ]
    },
    {
      "name": "Webhook receiver notes",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "X-Elvesora-Event",
            "value": "list.completed"
          },
          {
            "key": "X-Elvesora-Delivery",
            "value": "8a0b4b85-0d58-4f44-bd99-875adfd70d5f"
          },
          {
            "key": "X-Elvesora-Signature",
            "value": "sha256=<hmac>"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"id\": \"8a0b4b85-0d58-4f44-bd99-875adfd70d5f\",\n  \"event\": \"list.completed\",\n  \"created_at\": \"2026-06-10T10:15:30+00:00\",\n  \"team_id\": 123,\n  \"data\": {\n    \"list\": {\n      \"id\": 456,\n      \"name\": \"June accounts\",\n      \"records_total\": 500,\n      \"records_processed\": 500,\n      \"records_enriched\": 412,\n      \"match_rate\": 82.4\n    }\n  }\n}"
        },
        "url": {
          "raw": "https://example.com/elvesora/webhooks",
          "protocol": "https",
          "host": [
            "example",
            "com"
          ],
          "path": [
            "elvesora",
            "webhooks"
          ]
        },
        "description": "Receiver example only. Verify X-Elvesora-Signature with the endpoint secret using HMAC-SHA256 over the raw JSON body."
      }
    }
  ]
}