> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/vantage-api/labs.md).

# Labs

Find lab draw sites near a patient for go-to-lab tests.

## List nearby lab draw sites

> Lists Patient Service Centers (lab draw sites) near a US zip code, to choose from when placing a \`GO\_TO\_LAB\` order.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"labs","summary":"Labs","description":"Find lab draw sites near a patient for go-to-lab tests."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ListLabsResponse":{"type":"object","required":["labs"],"properties":{"labs":{"type":"array","items":{"$ref":"#/components/schemas/PSCLocation"}}}},"PSCLocation":{"description":"A Patient Service Center (lab draw site).","type":"object","required":["code","name","address","phone","latitude","longitude","scheduling","distance"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"},"description":"Opening hours keyed by weekday."},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean","description":"Whether online scheduling is open."},"distance":{"type":"number","description":"Miles from the requested zip."}}},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}}},"paths":{"/api/v1/labs":{"get":{"operationId":"listLabs","summary":"List nearby lab draw sites","tags":["labs"],"description":"Lists Patient Service Centers (lab draw sites) near a US zip code, to choose from when placing a `GO_TO_LAB` order.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"zip_code","in":"query","required":true,"description":"A 5-digit US zip code, optionally with its 4-digit suffix.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Nearby lab draw sites","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLabsResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid zip code. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```
