Greyfinch Apps FAQ

There are two access paths:

• Personal Access Token — for direct API queries. Generate one from your account settings in the Connect dashboard.

• App key + client keys — for app-based integrations. You receive an app key from the platform team; client keys are then auto-generated per tenant as practices install your app.

See the Authentication & Security guide for the full credential model.

Yes — each distinct app requires a unique app key, which the platform team provides. Once you have one, you can generate client keys on the fly as customers install the app. The same app key is also used for any direct API access your app needs against a tenant's data.

The full schema and GraphQL API reference are in the API Reference section of these docs. You can run interactive queries against a live environment via the Playground.

Patients, appointments, treatment plans, clinical data, financials, leads, and more. See the API Reference for the full set of available queries and types.

Available mutations are listed in the API Reference. Mutations are added on a needs basis — if you need a specific one that isn't there yet, reach out and we can add it to the roadmap.

Yes. External mappings let you associate a Connect record with an identifier from your own system using an app, so you can maintain relationships across both platforms without Connect needing to know your internal data model.

Each practice (tenant) gets its own client key, derived from your app key and can be automatically generated. Your app requests a client key when a clinic installs it, and uses that key for all subsequent API calls scoped to that tenant. See the Authentication & Security guide for the full lifecycle including the onInstall hook pattern.

There is no formal programme currently, but partnership discussions are open. Contact us to start a conversation.

Yes. Apps go through a beta phase with a small set of practices before being approved for listing in the app directory.

Pricing is discussed per-integration depending on your use case. Contact us for details.

Yes, via the Automations Hub. Apps can define automations that fire on events — appointment state changes, new patient records, and more. Automations are installed automatically when a clinic installs your app.

Automations can respond to appointment lifecycle changes: scheduled, confirmed, rescheduled, cancelled, no-show, and completed.

See Best Practices for guidance on staying within limits and avoiding unnecessary polling.

It depends on query complexity. Simple queries run in the tens of milliseconds; more complex queries with multiple relations will take longer.

Yes. A demo environment is available for initial exploration before you become a partner. Once you are a partner, a training environment with your own dedicated tenant is provisioned.

warning

Do not use production for testing.

Yes — apps must be tested in the training environment before they can go live.

You will generally need to seed your own test data. The training environment resets daily, though app keys and credentials persist across resets. If you have specific data requirements, reach out and we will see what we can accommodate.

Please ensure the endpoint you are using IS NOT https://connect.greyfinch.com/graphql - correct endpoints are documented in our API documentation

All data is hosted in AWS US East (N. Virginia).

Yes, a BAA is included in the integration agreement.

PHI is not masked at the API level. Partners are expected to be HIPAA compliant and manage PHI appropriately on their end. Because this is GraphQL, you can omit PHI/PII fields from your queries entirely if your use case doesn't require them.

There are no specific audit logging requirements imposed on integration partners. API interactions are tracked on the platform side.

GraphQL is versionless, so there are no versioned endpoints to manage. The platform is in active development approaching v1.0, and changes are currently focused on additions and enhancements rather than breaking changes. If a breaking change is unavoidable, partners are notified in advance and backwards compatibility is maintained where possible.

Fields prefixed with unstable are fully functional today but are flagged as likely to change shape in a future version. It is safe to use them, but be aware they may be updated in later versions.

Primarily enhancements and new mutations without breaking changes. If you have a specific feature need, reach out — we prioritise based on partner demand.

It depends on what your integration needs to do:

• API only is sufficient if you need to read or sync data — patients, appointments, financials, leads, etc.

• Apps Framework (or a combination) is the right path if your integration involves any of the following:

  • Writing data back to the patient chart

  • Embedding UI inside the practice management system

  • Triggering actions based on events within the system

See the Introduction for an overview of both paths.

Yes. See the Query Examples section for appointment query patterns.

AppointmentBooking.state. The full set of possible values is defined in the AppointmentBookingStateEnum.

Yes. Treatment.status holds the current status of a treatment record.

A lead configuration must exist before you can create any leads via the API — but you only need one per organisation. Once created, all leads for that organisation are submitted using that single configuration ID. You do not create a new configuration for each lead.

The configuration tells the system the source of incoming leads and controls whether patients are auto-created from them. For organisations with multiple locations, create it at the organisation level rather than at a specific location. You can then assign a location per lead at creation time, or leave it unset for a PMS user to assign manually.

By default, a patient record is automatically created as soon as a lead has enough personal information — first name, last name, email, and phone. This conversion happens asynchronously.

leadOnly mode disables that behaviour. The lead stays as a lead regardless of how much information it has, and a patient is only created when you explicitly call the promote mutation. Use this when you want to control or gate the conversion — for example, after a qualification step on your side.

You can enable leadOnly when creating the configuration, or add it to an existing one.

Use the insertLeadConfigurationSetting mutation:

mutation InsertLeadConfigurationSetting {
  insertLeadConfigurationSetting(
    object: { configurationId: "<<uuid>>", key: "leadOnly", value: true }
  ) {
    id
  }
}

Yes. Pass an answers array when creating the lead — each entry is a question/answer pair. These appear in the leads interface inside the PMS, visible to clinic staff when they view the lead.

answers: [
  { question: "How did you hear about us?", answer: "Google" }
  { question: "Preferred appointment time?", answer: "Mornings" }
]

Auto-conversion is asynchronous — the patient may not exist immediately after you create the lead. To check, query the lead by its ID and inspect the linked patient ID. If conversion has completed it will be present; if not, it will be null and you should poll again shortly after.

Use the createPatientFromLead mutation with the lead's ID:

mutation createPatientFromLead {
  createPatientFromLead(leadId: "<<uuid>>") {
    id
  }
}

This is only needed when leadOnly mode is enabled. In the default configuration, promotion happens automatically once sufficient information is present. Once promoted, you can carry out further operations — such as booking appointments — against the resulting patient record.

Yes. If a patient is created from a lead — either automatically via the leads integration or through manual promotion in the system — the lead ID and patient ID are linked. A patient is automatically created when an appointment is scheduled through the Leads flow. Otherwise, the record remains a lead until it is explicitly promoted.

See the Working with Leads guide for the full workflow including configuration, lead creation, and promotion.