Skip to main content

​
Prerequisites

  • A Peepal project created in the dashboard
  • An API key created for that project
  • Your Peepal API base URL
Your API key determines the project context, so you do not include a project ID in the URL.

​
Step 1: Create a job

Create a job with a person seed and at least one claim. 
BASE_URL="https://api.peepal.dev"
API_KEY="peepal_key_123"

curl -X POST "$BASE_URL/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "person": {
      "full_name": "Ada Lovelace",
      "email": "[email protected]",
      "linkedin_url": "https://www.linkedin.com/in/ada-lovelace"
    },
    "claims": [
      {
        "claim_key": "edu_1",
        "claim_type": "education",
        "expected": {
          "school": "University of London",
          "degree": "Mathematics"
        }
      },
      {
        "claim_key": "emp_1",
        "claim_type": "employment",
        "expected": {
          "employer": "Analytical Engines Ltd",
          "title": "Researcher"
        }
      }
    ]
  }'
The response includes the job ID and status. Store the id for the next steps.

​
Step 2: Poll for completion

Jobs run asynchronously. Poll the job endpoint until the status is completed. 
curl -s "$BASE_URL/v1/jobs/$JOB_ID" \
  -H "x-api-key: $API_KEY"

​
Step 3: Fetch the report

When the job is completed, request the report. 
curl -s "$BASE_URL/v1/jobs/$JOB_ID/report" \
  -H "x-api-key: $API_KEY"

​
Advanced: Add options and webhooks

Use options to control depth, sources, and webhook delivery. 
curl -X POST "$BASE_URL/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "Idempotency-Key: job_ada_001" \
  -d '{
    "person": {
      "full_name": "Ada Lovelace",
      "email": "[email protected]"
    },
    "claims": [
      {
        "claim_key": "id_1",
        "claim_type": "identity",
        "expected": {
          "github_url": "https://github.com/ada"
        },
        "match_rules": {
          "match_strength": "semantic",
          "min_confidence": 0.7
        }
      }
    ],
    "options": {
      "depth": "deep",
      "max_sources": 50,
      "exa_category": "people",
      "allow_domains": ["mit.edu"],
      "webhook": {
        "endpoint_id": "wh_123",
        "events": ["job.completed", "job.failed"]
      }
    }
  }'
Use Idempotency-Key when retrying create requests so you do not create duplicate jobs.