Skip to the content
EnrichedNowDocs

    Type to search every page.

    API reference

    Every endpoint of version 1, with its parameters and the shape it returns.

    Version 1 of the API. Every path starts with /v1.

    Text
    https://api.enrichednow.com/v1

    Conventions#

    FormatJSON in, JSON out. Send Content-Type: application/json with a body.
    TimesRFC 3339, in UTC, to the microsecond: 2026-11-16T20:27:29.418918Z.
    IdsStrings with a prefix that says what they are: acc_, usr_, key_, run_.
    AuthAuthorization: Bearer <key> — see Authentication.
    Errors{"error": {"code", "message", "details"}} with a matching HTTP status — see Errors.
    PagingList endpoints return next_cursor. Pass it back as cursor for the next page; null means the end.

    Endpoints#

    Method and pathAuthDoes
    GET /v1/healthNoneSays the service is up.
    GET /v1/scrapersNoneLists the scrapers.
    GET /v1/scrapers/{id}NoneOne scraper, with its schemas.
    POST /v1/scrapers/{id}/runsKeyStarts a run.
    GET /v1/runsKeyLists your runs.
    GET /v1/runs/{id}KeyOne run.
    GET /v1/runs/{id}/recordsKeyA run's records.
    POST /v1/runs/{id}/cancelKeyAsks a run to stop.
    GET /v1/usageKeyUnits charged in a period.
    POST /v1/auth/signupNoneCreates an account. Console.
    POST /v1/auth/loginNoneStarts a session. Console.
    POST /v1/auth/logoutSessionEnds the session. Console.
    GET /v1/meSessionThe signed-in user and account. Console.
    GET /v1/keysSessionLists API keys. Console.
    POST /v1/keysSessionCreates an API key. Console.
    DELETE /v1/keys/{id}SessionRevokes an API key. Console.

    Where the table says Key, the console's session is accepted as well. Where it says Session, a key is not accepted.

    The same list, machine-readable, is the OpenAPI document at GET /v1/openapi.json.

    An address that does not exist — or a method an address does not have — answers 404 not_found.

    Service#

    GET /v1/health#

    No authentication.

    Shell
    curl "https://api.enrichednow.com/v1/health"
    JSON
    { "status": "ok" }

    Catalogue#

    GET /v1/scrapers#

    The public catalogue: every scraper that is available. No authentication.

    Shell
    curl "https://api.enrichednow.com/v1/scrapers"
    200 · JSON
    {
      "scrapers": [
        {
          "id": "ats.board",
          "version": 1,
          "title": "ATS job board",
          "summary": "Job openings from one board of an applicant tracking system (Greenhouse, Lever, Ashby, Workday and others).",
          "mode": "job",
          "billing_unit": "request",
          "data_class": "public",
          "availability": "public"
        },
        {
          "id": "careers.company",
          "version": 1,
          "title": "Company careers site",
          "summary": "Job openings from a company's own careers site: give its domain or its careers page.",
          "mode": "job",
          "billing_unit": "request",
          "data_class": "public",
          "availability": "public"
        }
      ]
    }

    Each item is a ScraperCard, without the schemas.

    GET /v1/scrapers/{id}#

    One scraper, with the JSON Schema of its input (input_schema) and of the records it returns (record_schema). No authentication.

    Shell
    curl "https://api.enrichednow.com/v1/scrapers/ats.board"

    Returns a ScraperCard including both schemas (shortened here):

    200 · JSON
    {
      "id": "ats.board",
      "version": 1,
      "title": "ATS job board",
      "summary": "Job openings from one board of an applicant tracking system (Greenhouse, Lever, Ashby, Workday and others).",
      "mode": "job",
      "billing_unit": "request",
      "data_class": "public",
      "availability": "public",
      "input_schema": {
        "…": "JSON Schema"
      },
      "record_schema": {
        "…": "JSON Schema"
      }
    }
    ErrorWhen
    404 not_foundNo scraper has this id, or the scraper is not publicly available.

    The scraper pages on this site are generated from the same schemas.

    Runs#

    POST /v1/scrapers/{id}/runs#

    Starts a run of the scraper {id}. Guide: Running a scraper.

    Query

    ParameterTypeMeaning
    waitnumber, 0 to 60, default 0Seconds to hold the request open for the run to end. Fractions are accepted.

    Body

    FieldTypeMeaning
    inputobjectRequired. The scraper's input. Its fields are the scraper's input_schema. The body takes no other field.
    Shell
    curl -X POST "https://api.enrichednow.com/v1/scrapers/ats.board/runs?wait=60" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"input": {"board_url": "https://boards.greenhouse.io/acme"}}'

    Returns a Run:

    StatusWhen
    200The run ended within wait. The run is final.
    202The run was accepted and has not ended yet: it is queued or running. Without wait, this is the answer.
    202 · JSON
    {
      "id": "run_eb3c3302a5eb6987c17f3b53",
      "scraper_id": "careers.company",
      "scraper_version": 1,
      "status": "queued",
      "reason": null,
      "input": {
        "domain": "example.com"
      },
      "record_count": 0,
      "units": 0,
      "diagnostics": null,
      "created_at": "2026-11-16T20:27:31.253846Z",
      "started_at": null,
      "finished_at": null
    }
    ErrorWhen
    401 unauthorizedNo valid key.
    404 not_foundNo such scraper, or it is not publicly available.
    422 invalid_inputinput does not fit the scraper's schema, wait is out of range, or the body is not {"input": {...}}. details.fields lists each problem.
    402 quota_exceededThe account's allowance is used up. details carries used_units and allowance_units.
    429 too_many_runsThe account is at its concurrent-run limit. details carries active_runs and max_concurrent_runs.

    None of these creates a run.

    GET /v1/runs#

    Your account's runs, newest first.

    Query

    ParameterTypeMeaning
    limitinteger, 1 to 100, default 20Runs per page.
    cursorstringThe next_cursor of the previous page.
    scraper_idstringOnly runs of this scraper.
    statusstringOnly runs with this status.
    Shell
    curl "https://api.enrichednow.com/v1/runs?scraper_id=ats.board&status=unsupported" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY"
    200 · JSON
    {
      "runs": [
        {
          "id": "run_9eebae2bc0db3036c9893cda",
          "scraper_id": "ats.board",
          "scraper_version": 1,
          "status": "unsupported",
          "reason": "render_required",
          "input": {
            "board_url": "https://jobs.dayforcehcm.com/en-US/acme/CANDIDATEPORTAL"
          },
          "record_count": 0,
          "units": 0,
          "diagnostics": {
            "requests": 0,
            "bytes": null,
            "wall_ms": 0,
            "facts": {
              "ats": "dayforce"
            }
          },
          "created_at": "2026-11-16T20:27:29.617445Z",
          "started_at": "2026-11-16T20:27:29.619938Z",
          "finished_at": "2026-11-16T20:27:29.623160Z"
        },
        {
          "id": "run_d783786ba1ae8662767c764e",
          "scraper_id": "ats.board",
          "scraper_version": 1,
          "status": "unsupported",
          "reason": "unknown_board",
          "input": {
            "board_url": "https://jobs.acme.com/openings"
          },
          "record_count": 0,
          "units": 0,
          "diagnostics": {
            "requests": 0,
            "bytes": null,
            "wall_ms": 0,
            "facts": {}
          },
          "created_at": "2026-11-16T20:27:29.606933Z",
          "started_at": "2026-11-16T20:27:29.610174Z",
          "finished_at": "2026-11-16T20:27:29.613181Z"
        }
      ],
      "next_cursor": null
    }

    runs is a list of Run. 422 invalid_input for a limit out of range, a status that is not one, or a cursor this API did not give out.

    GET /v1/runs/{id}#

    One run, as it is now.

    Shell
    curl "https://api.enrichednow.com/v1/runs/run_6cce2b12aaf37a10b5e1b885" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY"

    Returns a Run. 404 not_found when your account has no such run.

    200 · JSON
    {
      "id": "run_6cce2b12aaf37a10b5e1b885",
      "scraper_id": "ats.board",
      "scraper_version": 1,
      "status": "ok",
      "reason": null,
      "input": {
        "board_url": "https://boards.greenhouse.io/acme"
      },
      "record_count": 19,
      "units": 1,
      "diagnostics": {
        "requests": 1,
        "bytes": 232779,
        "wall_ms": 565,
        "facts": {
          "careers_url": "https://boards.greenhouse.io/acme",
          "discovery": "supplied",
          "ats": "greenhouse",
          "pages_read": 1,
          "renders_refused": 0
        }
      },
      "created_at": "2026-11-16T20:27:29.009834Z",
      "started_at": "2026-11-16T20:27:29.013803Z",
      "finished_at": "2026-11-16T20:27:29.582787Z"
    }

    GET /v1/runs/{id}/records#

    The records a run stored, in the order it stored them. Records are kept for 7 days after the run ended.

    Query

    ParameterTypeMeaning
    limitinteger, 1 to 1000, default 100Records per page.
    cursorstringThe next_cursor of the previous page.
    Shell
    curl "https://api.enrichednow.com/v1/runs/run_6cce2b12aaf37a10b5e1b885/records?limit=1000" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY"

    Returns

    FieldTypeMeaning
    recordslistOne page of records. Empty for a run that stored none.
    next_cursorstring or nullPass it back as cursor for the next page; null at the end.
    expiredtruePresent only when the records are gone because the 7 days have passed.

    Each record has the shape of the scraper's record_schema — see the scraper pages. A page asked for with limit=2 (the records themselves are left out here), and the answer once the records have expired:

    200 · JSON
    {
      "records": [
        {
          "…": "a record"
        },
        {
          "…": "a record"
        }
      ],
      "next_cursor": "Mg"
    }
    200 · JSON
    {
      "records": [],
      "next_cursor": null,
      "expired": true
    }

    POST /v1/runs/{id}/cancel#

    Asks a run to stop. No body.

    Shell
    curl -X POST "https://api.enrichednow.com/v1/runs/run_6cce2b12aaf37a10b5e1b885/cancel" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY"

    Returns the Run with 200, as it is at that moment: cancelled for a run that was still queued, usually still running for one that was running, and unchanged for one that had already ended. Cancelling is cooperative: a run that was already finishing may still complete, so poll for the status it ends with — see Cancel a run. A run that ends cancelled costs nothing and keeps the records it had found.

    Usage#

    GET /v1/usage#

    Units charged in a period. Guide: Usage and units.

    Query

    ParameterTypeMeaning
    fromdateFirst day of the period (UTC), included. Default: the 1st of the month to falls in.
    todateLast day of the period (UTC), included. Default: today.
    group_byday or scraper, default dayWhat one row stands for.

    A period is at most 366 days, and must not end before it starts: otherwise 422 invalid_input.

    Shell
    curl "https://api.enrichednow.com/v1/usage?from=2026-11-01&to=2026-11-30&group_by=day" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY"

    Returns

    FieldTypeMeaning
    periodobjectThe period covered: from and to.
    total_unitsintegerUnits charged in the period.
    allowance_unitsintegerThe account's allowance for a calendar month.
    rowslistkey, units and runs (the charged runs). By day: one row for every day of the period. By scraper: one row for each scraper that was charged, most units first.
    200 · JSON
    {
      "period": {
        "from": "2026-11-16",
        "to": "2026-11-16"
      },
      "total_units": 1,
      "allowance_units": 1000,
      "rows": [
        {
          "key": "2026-11-16",
          "units": 1,
          "runs": 1
        }
      ]
    }

    Console endpoints#

    These are what the console itself calls. They use a session cookie, not an API key, and you do not need them to use the API. A session is a cookie named enrichednow_session (HttpOnly, SameSite=Lax, 30 days) set by signing up or logging in. Requests that change something — every POST and DELETE made with the session, starting and cancelling runs included — must also send the header X-CSRF-Token, with the csrf_token value that signing up, logging in and GET /v1/me return; without it the answer is 403 forbidden.

    Signing up and logging in are limited to 20 attempts a minute: 429 rate_limited, with a Retry-After header.

    POST /v1/auth/signup#

    Creates a user and an account, and starts a session.

    FieldTypeMeaning
    emailstringThe user's email address. Kept in lowercase.
    passwordstringThe password, at least 8 characters. Stored only as a scrypt hash.
    account_namestringA name for the account, at most 200 characters.

    Returns 201 with Me and sets the session cookie:

    Request and status
    POST /v1/auth/signup
    
    HTTP 201
    Set-Cookie: enrichednow_session=<session token>; HttpOnly; Max-Age=2592000; Path=/; SameSite=lax
    201 · JSON
    {
      "user": {
        "id": "usr_a750fc675f1e87d6e8f8e445",
        "email": "you@acme.com"
      },
      "account": {
        "id": "acc_6d354f1d8ef38533377cc8db",
        "name": "Acme",
        "allowance_units": 1000,
        "max_concurrent_runs": 2
      },
      "csrf_token": "csrf-token-from-GET-/v1/me"
    }

    422 invalid_input when a field does not fit, or when an account with this email already exists:

    422 · JSON
    {
      "error": {
        "code": "invalid_input",
        "message": "An account with this email already exists.",
        "details": {
          "fields": [
            {
              "path": "email",
              "message": "An account with this email already exists."
            }
          ]
        }
      }
    }

    POST /v1/auth/login#

    Starts a session. The body is email and password. Returns 200 with Me and sets the session cookie. A wrong email or password — the answer does not say which — is 401 unauthorized:

    401 · JSON
    {
      "error": {
        "code": "unauthorized",
        "message": "The email or the password is wrong.",
        "details": {}
      }
    }

    POST /v1/auth/logout#

    Ends the session. Needs the X-CSRF-Token header. Returns 204 with no body and clears the cookie.

    GET /v1/me#

    The signed-in user, their account, and the CSRF token. Returns Me.

    GET /v1/keys#

    The account's API keys, without their secrets.

    200 · JSON
    {
      "keys": [
        {
          "id": "key_02f1e08e65f29703d1b463e7",
          "name": "production",
          "prefix": "k3J9xQ2m",
          "created_at": "2026-11-16T20:27:28.985324Z",
          "last_used_at": "2026-11-16T20:27:28.990857Z",
          "revoked_at": null
        }
      ]
    }

    keys is a list of Key, newest first. A revoked key stays in the list, with its revoked_at.

    POST /v1/keys#

    Creates an API key.

    FieldTypeMeaning
    namestringA name for the key, at most 100 characters.

    Returns 201 with the Key and one more field, secret — the key itself. This is the only time the secret is returned. (The secret below is a placeholder in the real format.)

    201 · JSON
    {
      "id": "key_02f1e08e65f29703d1b463e7",
      "name": "production",
      "prefix": "k3J9xQ2m",
      "created_at": "2026-11-16T20:27:28.985324Z",
      "last_used_at": null,
      "revoked_at": null,
      "secret": "en_live_k3J9xQ2mT7vB1nR5cW8yZ4aD6fH0jL2pS9uX3eG7iK1"
    }

    DELETE /v1/keys/{id}#

    Revokes a key. Returns 204 with no body. The key stops working at once: the next request with it is answered 401. Revoking a key twice is still 204; 404 not_found when the account has no such key.

    Shapes#

    ScraperCard#

    FieldTypeMeaning
    idstringThe scraper's id: family.name, such as ats.board.
    versionintegerThe scraper's version.
    titlestringA short name.
    summarystringOne sentence on what it returns.
    modesync or jobsync: answers within one request. job: reads several pages and runs in the background.
    billing_unitrequest or recordWhat a charged run costs — see Usage and units.
    data_classstringThe kind of data returned. public for every scraper available today.
    availabilitypublic or internalOnly public scrapers are listed and can be run.
    input_schemaJSON SchemaThe input. Only on GET /v1/scrapers/{id}.
    record_schemaJSON SchemaOne record. Only on GET /v1/scrapers/{id}.

    Run#

    FieldTypeMeaning
    idstringrun_…
    scraper_idstringThe scraper that ran.
    scraper_versionintegerThe version of the scraper that ran.
    statusstringqueued, running, ok, partial, failed, unsupported or cancelled — see Statuses.
    reasonstring or nullA code when the status is not ok — see Reason codes.
    inputobjectThe input the run was started with.
    record_countintegerThe number of records stored.
    unitsintegerThe units charged — see Usage and units.
    diagnosticsobject or nullrequests, bytes, wall_ms and facts; null until the run ends — see Diagnostics.
    created_attimeWhen the run was accepted.
    started_attime or nullWhen execution began; null while the run is queued.
    finished_attime or nullWhen the run ended; null until then.
    200 · JSON
    {
      "id": "run_6cce2b12aaf37a10b5e1b885",
      "scraper_id": "ats.board",
      "scraper_version": 1,
      "status": "ok",
      "reason": null,
      "input": {
        "board_url": "https://boards.greenhouse.io/acme"
      },
      "record_count": 19,
      "units": 1,
      "diagnostics": {
        "requests": 1,
        "bytes": 232779,
        "wall_ms": 565,
        "facts": {
          "careers_url": "https://boards.greenhouse.io/acme",
          "discovery": "supplied",
          "ats": "greenhouse",
          "pages_read": 1,
          "renders_refused": 0
        }
      },
      "created_at": "2026-11-16T20:27:29.009834Z",
      "started_at": "2026-11-16T20:27:29.013803Z",
      "finished_at": "2026-11-16T20:27:29.582787Z"
    }

    Key#

    FieldTypeMeaning
    idstringkey_…
    namestringThe name given when it was created.
    prefixstringThe 8 characters that follow en_live_ in the key, shown so that you can tell your keys apart.
    created_attimeWhen it was created.
    last_used_attime or nullWhen it was last used (noted at most once a minute); null for a key never used.
    revoked_attime or nullWhen it was revoked; null for a key that works.
    secretstringThe key itself. Only in the answer of POST /v1/keys.

    Me#

    200 · JSON
    {
      "user": {
        "id": "usr_a750fc675f1e87d6e8f8e445",
        "email": "you@acme.com"
      },
      "account": {
        "id": "acc_6d354f1d8ef38533377cc8db",
        "name": "Acme",
        "allowance_units": 1000,
        "max_concurrent_runs": 2
      },
      "csrf_token": "csrf-token-from-GET-/v1/me"
    }

    csrf_token is the value of the X-CSRF-Token header (a placeholder stands in for it here).

    Error#

    404 · JSON
    {
      "error": {
        "code": "not_found",
        "message": "There is no run 'run_000000000000000000000000'.",
        "details": {}
      }
    }
    CodeHTTP
    unauthorized401
    quota_exceeded402
    forbidden403
    not_found404
    invalid_input422
    too_many_runs429
    rate_limited429
    internal500

    What each means and how to handle it: Errors.