Build the complete scheduling experience in your product.

Full API Integration is the primary path for applications that own customer discovery, identity, consent, ordering, questionnaires, appointment preferences, communications, and results. Follow the sequence below and use the API Reference for complete request and response schemas.

Know your integration configuration

Customer consent

Physician order

Supported configuration combinations

All six combinations are supported. Consent completes before order creation, and the physician-order branch begins after scheduling.

Full API Integration is the primary documentation flow. Your application owns every customer-facing step and uses Fitnescity Health APIs from discovery through scheduling, communications, and results.

End-to-end flow

1. 1. Discover locations, products, and availability
   GET /v1/locations → GET /v1/locations/{catalogId}/offerings/{offeringId}/products → GET /v1/locations/{catalogId}/offerings/{offeringId}/schedule

   Search by coordinates, carry catalog_id and offering_id into the selected offering, inspect product pricing and is_prescreening_required, and let the customer choose a primary appointment time plus one to three alternate availabilities from live schedule data. Each available_time is a full ISO-8601 datetime with the test location numeric offset, not always UTC; preserve it exactly. available_date is the calendar date at the test location.

2. 2. Create or update the customer identity
   POST /v1/api-first/identities

   Send a stable external_customer_id and the customer profile. Store data.customer_identity_id from the response and reuse it for customer-consent evidence or reusable consent, applicable Calcium Score prescreening, and orders for that customer.

3. 3. Establish the provisioned customer consent
   Fitnescity Health consent API: consent bundle → session → finalize

   API Partner-provided consent PDF: POST /v1/api-first/consent-evidence → server-side S3 upload → complete → poll

   Customer consent is required through exactly one provisioned branch. For the Fitnescity Health consent API, render and finalize the reusable consent and store grant.id. For an API Partner-provided consent PDF, use read:consent_evidence and write:consent_evidence, create PDF-only evidence no larger than 20 MiB, have your API Partner backend or server-side proxy upload the exact bytes with every required_headers value and checksum, complete the upload, poll until status=accepted, then use the evidence id as partner_consent_evidence_id before creating the order.

4. 4. Complete Calcium Score prescreening when required
   GET /v1/tests/{testType}/prescreen-form → POST /v1/tests/{testType}/prescreen-form/submissions

   When is_prescreening_required is true, submit customer_identity_id and prescreen.pcp_consent=true plus exactly the provisioned consent source: consent_grant_id or an accepted partner_consent_evidence_id. When it is false, skip both prescreen calls. A successful prescreen returns the order_id used to confirm the order.

5. 5. Create the order
   POST /v1/orders

   Send customer_identity_id or external_customer_id and the required customer profile. Supply exactly the provisioned consent source: consent_grant_id for the Fitnescity Health consent API or an accepted partner_consent_evidence_id for an API Partner-provided consent PDF. Store the returned order and appointment identifiers.

6. 6. Complete the appointment questionnaire
   GET /v1/tests/{testType}/scheduling-questionnaire → GET/POST /v1/appointments/{appointmentId}/scheduling-questionnaire

   Use the test-type route to preview the current questionnaire. After order creation, fetch the appointment-scoped definition and submit its questionnaire_definition_id and content_hash with answers and acknowledgements keyed by the returned item ids. Successful submissions are finalized synchronously with outcome.status accepted, blocked, or physician_review_required; outcome.code is nullable and forward-compatible.

7. 7. Request scheduling
   POST /v1/appointments/{appointmentId}/schedule

   Send selected_appointment_date and one to three alternate_availabilities as the full ISO-8601 datetimes and numeric offsets returned by schedule availability. They are not always UTC. This is a request-then-confirm flow: pending_confirmation means the request was accepted and is awaiting confirmation, not that the appointment is confirmed.

8. 8. Establish the provisioned physician order
   Fitnescity Health physician-order service: monitor the appointment

   Structured physician-order API: bundle → session → finalize → poll

   API Partner-provided physician-order PDF: POST /v1/api-first/appointments/{appointmentId}/physician-order-evidence → server-side S3 upload → complete → poll

   After scheduling, follow exactly the provisioned physician-order branch. For the Fitnescity Health physician-order service, submit no physician evidence and monitor physician_order_status plus appointment.form_available. For the Structured physician-order API, create, render, and finalize the frozen session, then poll for its artifact. For an API Partner-provided physician-order PDF, upload appointment-scoped evidence with read:physician_order_evidence and write:physician_order_evidence and wait for status=accepted.

9. 9. Track confirmation, forms, communications, and results
   GET /v1/appointments and GET /v1/appointments/{appointmentId}/check-in-link

   GET /v1/appointments/{appointmentId}/signed-form

   Read appointment status and physician_order_status through appointment endpoints or webhooks. After the appointment is confirmed, request the opaque check-in link server-side and place it in API Partner-owned email or SMS. The view-only page shows the customer, appointment time, test, facility/location, and appointment ID; the link expires six hours after appointment start, is not included in appointment resources or webhooks, and must not be logged or parsed. Request a new link after rescheduling; cancellation, refund, and no-show invalidate it. Subscribe to appointment.form_available; when it arrives, call the signed-form endpoint to obtain a temporary download URL. Use the shared email and text/SMS communication model and poll GET /v1/results for completed results.

Consent signature metadata

API Partner-provided PDF lifecycle

This upload lifecycle applies only to the API Partner-provided consent PDF and API Partner-provided physician-order PDF branches. Use it for PDF evidence; it does not apply to API-rendered sessions.

1. 1. Calculate the document byte length, lowercase hexadecimal SHA-256, and base64 SHA-256 before creating evidence. API Partner evidence is PDF-only and limited to 20 MiB. Declare the file name, content type, byte length, and hash. The exact API Partner-provided PDF bytes are contract-trusted: contents are not content-inspected or normalized.
2. 2. Retain data.id and the returned upload session. From your API Partner backend or a server-side proxy, PUT the exact bytes to data.upload_session.url and include every required_headers entry exactly, including x-amz-checksum-sha256. The API gateway does not receive the document bytes, and browser code must not issue this S3 PUT. Upload the exact bytes used for the declared checksum; do not inspect, transform, or normalize them.
3. 3. If the server-side PUT returns 403 or 410, retain the evidence ID and POST the matching /upload-sessions endpoint with a stable idempotency key to obtain a replacement, then retry the PUT. Do not create another evidence record.
4. 4. Call the matching upload-session completion endpoint with the same lowercase hexadecimal sha256. Then GET the evidence resource until data.status=accepted. Never attach evidence that is still awaiting upload or processing. If completion returns 429 or 503, retry the same completion request with the same evidence ID, upload-session ID, hash, and stable idempotency key. If completion reports an expired upload session, try the replacement-session flow and read the evidence state. When its status is abandoned, start a new evidence record with a new create idempotency key instead of retrying the terminal record.

Structured physician-order API

After scheduling, fetch GET /v1/api-first/appointments/{appointmentId}/physician-order-bundle and save its template, content, context, and API Partner attestation metadata. Create the immutable presentation with POST /v1/api-first/appointments/{appointmentId}/physician-order-sessions.

1. 1. Render every presentation section, row, statement, and required acknowledgement verbatim and in response order. You may style the surrounding interface, but do not rewrite, omit, reorder, or reconstruct the physician-facing content.
2. 2. Capture both required physician acknowledgements: order_acknowledgement and electronic_signature_attestation. The returned partner_attestation is API Partner-system certification metadata; it is not another physician checkbox.
3. 3. Finalize with POST /v1/api-first/physician-order-sessions/{sessionId}/finalize, echoing the frozen template_version_id, content_hash, context_hash, presentation_hash, and the exact partner_attestation version and text hash.
4. 4. Respect the 202 Accepted, Location, and Retry-After response. Poll GET /v1/api-first/physician-order-sessions/{sessionId} until the artifact is available, then retrieve GET /v1/appointments/{appointmentId}/signed-form.
5. 5. If provider or order data changes, create a replacement using replaces_session_id, or abandon the open session with POST /v1/api-first/physician-order-sessions/{sessionId}/abandon. Do not edit a frozen session or fall back to the PDF or Fitnescity Health physician-order service branch.

This branch uses read:physician_order_evidence and write:physician_order_evidence and requires explicit onboarding enablement and certification.

Scheduling and form availability

Idempotency and recovery

HTTP/1.1 202 Accepted
Retry-After: 7

{
  "code": 202,
  "data": {
    "status": "in_progress",
    "code": "IDEMPOTENCY_IN_PROGRESS",
    "retry_after_seconds": 7
  },
  "error": null
}

Actionable errors

Full API Integration failures use the standard error envelope. Branch on the stable machine-readable value in error.details.code, not the human-readable message. The 202 outcome above places its identifier in data.code.

• CONSENT_GRANT_REQUIRED

  This API key is provisioned for the Fitnescity Health consent API. Finalize reusable consent and send the returned grant.id as consent_grant_id on the original logical request.

• CUSTOMER_CONSENT_NOT_REQUIRED

  Do not retry the reusable-consent request. This API key is not provisioned for the Fitnescity Health consent API; use the provisioned API Partner-provided consent PDF lifecycle.

• CONSENT_SESSION_OPEN

  Resume the open session or abandon it before starting a replacement.

• QUESTIONNAIRE_VERSION_MISMATCH

  Fetch the appointment-scoped definition again and submit its id and content hash.

• QUESTIONNAIRE_VALIDATION_FAILED

  Correct the answers or acknowledgements identified in the validation details.

• QUESTIONNAIRE_ALREADY_SUBMITTED

  The appointment already has an immutable finalized submission. A new Idempotency-Key cannot replace it; continue with the original result or contact support if the appointment itself must be corrected.

• SLOT_UNAVAILABLE

  Refresh availability and ask the customer to select another time.

• IDEMPOTENCY_CONFLICT

  Use the original payload with that key, or use a new key for a new logical request.

Prescreen rendering guidance

Treat GET /v1/tests/{testType}/prescreen-form as a render contract for prescreen-required tests. The goal is to let your app render the correct form without reverse-engineering labels or grouping from validation rules. Use the returned copy as the source for recommended labels, section titles, categories, consent language, and the primary CTA. The pcp_consent field is independent of reusable consent managed by Fitnescity Health.

• Render fields and sections in the returned array order.
• Use copy.sections for labels and section headings, copy.consent.label for the checkbox text, and submit_button_text for the primary CTA.
• For control=date_parts, render separate month, day, and year inputs but submit dob in MM/DD/YYYY format.
• For control=boolean_radio, render the returned options in the provided order.
• Display the returned copy verbatim unless you have an approved reason to override the wording.

{
  "code": 200,
  "data": {
    "required_fields": [
      "dob",
      "family_history_cardiovascular_disease",
      "high_cholesterol_or_hypertension",
      "diabetes",
      "bmi_higher_than_25",
      "sedentary_lifestyle",
      "smoker",
      "symptoms_heart_disease",
      "pregnant",
      "diagnosed_heart_disease",
      "pcp_name",
      "pcp_phone",
      "pcp_consent"
    ],
    "copy": {
      "sections": [
        {
          "id": "dob",
          "title": null,
          "fields": [
            {
              "name": "dob",
              "label": "What is your date of birth?",
              "control": "date_parts",
              "required": true
            }
          ]
        },
        {
          "id": "risk_factors",
          "title": "Risk Factors",
          "fields": [
            {
              "name": "family_history_cardiovascular_disease",
              "label": "Does heart disease run in your family?",
              "control": "boolean_radio",
              "options": ["Yes", "No"]
            }
          ]
        },
        {
          "id": "symptoms",
          "title": "Symptoms & Medical History"
        }
      ],
      "consent": {
        "field": "pcp_consent",
        "label": "By providing my Primary Care Physician's information..."
      },
      "submit_button_text": "Answer all questions to continue"
    }
  },
  "error": null
}