GraphQL

Request only the fields you need

Select only the fields your integration uses, and only fields shown in these docs. Some fields are not available to API partners; selecting one returns unauthorized and can null the object that contains it (see Fields not available to API partners).

Pass values as variables

Declare each input on the operation and send its value in variables. Never insert values into the query string. Variables are typed and checked by the API and need no escaping.

query GetQuoteRequest($id: ID!) {  quoteRequest(id: $id) {    id    status  }}

Name every operation

Give every operation a name, such as query ListQuoteRequests, and send it as operationName. A document with more than one operation and no operationName is rejected. Include the name when you contact support about a request.

Check errors on every response

Treat a response as successful only when errors is missing or empty. HTTP 200 alone does not mean the operation succeeded. See Errors for the common messages and how to read validation errors.

Handle partial results

When a response has both data and errors, use the fields that have values and handle each error by its path. Do not read a null field as "no value" without checking whether an error names it (see Partial success).

Use fragments for repeated selections

When several operations select the same fields of a type, define them once as a fragment and include it with ...Name.

query ClientQuoteRequests($first: Int!, $clientId: ID!) {  quoteRequests(first: $first, clientId: $clientId) {    edges {      node {        ...QuoteRequestSummary      }    }  }}fragment QuoteRequestSummary on QuoteRequest {  id  status  productType}

Paginate with cursors

• List operations return a connection. Pass first on every request; leaving it out returns an error.
• Each list operation has a maximum page size. A larger first is reduced to the maximum without an error.
• To get the next page, pass pageInfo.endCursor from the last response as after.
• Stop when hasNextPage is false or a page has no edges. hasNextPage can be true when the next page is empty.
• Treat cursors as opaque. Do not decode, build or store them.

query ListQuoteRequests($first: Int!, $after: String) {  quoteRequests(first: $first, after: $after) {    pageInfo {      hasNextPage      endCursor    }    edges {      node {        id      }    }  }}

Retry only requests that can succeed on retry

• Do not retry a request that failed with a validation error, unauthorized, not_found, or a 400, 401 or 404 status. Fix the request first.
• Retry network failures, timeouts and 5xx statuses with exponential backoff and a limit on attempts.
• Set a timeout on every request. Treat a timeout as an unknown outcome, not a failure.
• You can retry a query safely. Before you retry a mutation whose outcome is unknown, query for the record first: repeating createClient or createQuoteRequest creates a duplicate, and duplicate clients or submissions may delay quote delivery.

Use these docs as the schema reference

The operations and fields documented here are the ones supported for API partners. The schema contains more types and fields than API partners can use, and an undocumented field may return unauthorized or change without notice. Do not discover operations or fields from the schema itself. If you need data that is not documented, contact api@corvusinsurance.com.

Read fields by name and allow for null

Do not depend on the order of keys in a response; read each field by name. A field whose type has no ! can be null. Handle null for every such field you select.