---
title: "Screen a species list against the species registers held, in one call"
method: POST
path: "/designations"
---

# Screen a species list against the species registers held, in one call

`POST /designations`

## Request

- Base URL: `https://passage-data.com/api/v1`
- URL: `https://passage-data.com/api/v1/designations`
- Auth: one of:
  - none
  - HTTP bearer
  - API key in header `x-api-key`

Up to 500 names, each answered by find_designations itself: its designations with their cites and the registers searched that are `silent` on it with what each one's silence means, or its own coded refusal (designations.none_held = no register searched names it, a statement about these registers and never that the species is unprotected; species.ambiguous with candidates; species.unreadable). A register's instrument, title, edition, place, note for the place, source URL and sha256 are sent once, in `registers`: a designation, its cite or a silent entry leaves out a field only where its value is the register's. A designation without `outcome_says` says `outcomes[outcome]`; a reconciled name without `source` is read from `backbone`. `summary` counts the names listed, listed only under a population or subspecies, watch-listed, named but listed by none, named by no register, ambiguous and refused, and how many names each register lists. Use it instead of one call a name: the door allows 30 calls in 10 seconds.

## Request body

- object
  - `species` string[], required: The names as the list prints them: scientific names (authorship allowed) or common names exactly as a register prints them.
  - `place` string: ISO 3166 code of where the species are: US, CA, GB, FR, US-CA, CA-ON, GB-SCT. Omit to search every register.

## Response `200`

One result a name, in the list's order, beside the registers they name and a summary; or the call refused once (place.malformed)

- ScreenSpecies
  - `query` object
  - `searched` object
  - `summary` object
    - `names` integer
    - `listed` integer
    - `listed_qualified` integer
    - `watch_listed` integer
    - `named_not_listed` integer
    - `none_held` integer
    - `ambiguous` integer
    - `refused` integer
    - `refused_by` object
    - `listed_by` object
    - `says` string
  - `packed_as` string
  - `registers` object
  - `outcomes` object
  - `backbone` object
  - `results` object[]
    - `index` integer
    - `outcome` 'listed' | 'listed_qualified' | 'watch_listed' | 'named_not_listed' | 'none_held' | 'ambiguous' | 'refused'
    - `query` object
    - `name` object
    - `total` integer
    - `designations` Designation[]
      - `register` string
      - `name` string
      - `status` string
      - `outcome` string
      - `outcome_says` string
      - `matched_at` string
      - `place` string[]
      - `legal_instrument` boolean
      - `kind` string
      - `population` string, nullable
      - `asks` string, nullable
      - `note` string, nullable
      - `cite` Cite
        - `instrument` string
        - `title` string
        - `issuer` string, nullable
        - `edition` string, nullable
        - `section` string, nullable
        - `page` union
          - integer
          - string
        - `quote` string, nullable
        - `source_url` string, nullable
        - `source_sha256` string, nullable
        - `source_status` object: What the daily edition watch last saw at the source: status unchanged, changed (with changed_on and says: the rows are as read from the edition named, not yet re-read) or not verified; checked is the day.
          - `checked` string
          - `status` 'unchanged' | 'changed' | 'not verified'
          - `changed_on` string
          - `says` string
        - `note` string: What the register prints beside the value (e.g. a later or earlier value and its date).
        - `table` string
        - `column` string: The register column the value sits in (e.g. mcl, mclg).
    - `silent` object[]
    - `refused` object
  - `refused` object

## Other responses

- `400`: species.missing, species.malformed, species.too_many (over 500), place.malformed, body.malformed
- `413`: body.too_large

---

[API](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits.md) · [All operations](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits/llms.txt) · [OpenAPI document](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits/revisions/ba066708bf53?raw)