Skip to main content

Getting Started

This guide will help you make your first API call to Prospyr in under 5 minutes.

Prerequisites​

Before you begin, you'll need:

  • An API Key, you can retreive one by logging into Prospyr and going to Settings > Data > API Keys
  • A tool to make HTTP requests (curl, Postman, or your favorite programming language)

Step 1: Set Up Your Environment​

  1. Open the Prospyr Public API Documentation Postman Collection
  2. Fork the collection to your workspace
  3. Go to the collection's Variables tab
  4. Set your JWT token in the token variable
  5. Save your changes

Option B: Using Code​

Set up your environment variables:

export PROSPYR_JWT_TOKEN="your_jwt_token_here"
export PROSPYR_API_URL="https://prod.prospyrmedapi.com/v1/graphql"

Step 2: Make Your First Request​

Let's search for patients to verify your setup is working:

Using curl​

curl -X POST $PROSPYR_API_URL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PROSPYR_JWT_TOKEN" \
  -H "app: api" \
  -d '{"query": "query searchPatients { searchPatients(args: { search: \"john\" }, limit: 5) { ...PatientSearchFields } }"}'

Using JavaScript (Node.js)​

const axios = require('axios');

const query = `
  query searchPatients {
    searchPatients(args: { search: "john" }, limit: 5) {
      ...PatientSearchFields
    }
  }
`;

axios.post(process.env.PROSPYR_API_URL, 
  { query },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.PROSPYR_JWT_TOKEN}`,
      'app': 'api'
    }
  }
)
.then(response => console.log(JSON.stringify(response.data, null, 2)))
.catch(error => console.error('Error:', error.response?.data || error.message));

Using Python​

import os
import requests
import json

query = """
query searchPatients {
  searchPatients(args: { search: "john" }, limit: 5) {
    ...PatientSearchFields
  }
}
"""

headers = {
    'Content-Type': 'application/json',
    'Authorization': f"Bearer {os.environ['PROSPYR_JWT_TOKEN']}",
    'app': 'api'
}

response = requests.post(
    os.environ['PROSPYR_API_URL'],
    json={'query': query},
    headers=headers
)

print(json.dumps(response.json(), indent=2))

Step 3: Understanding the Response​

A successful response will look like:

{
  "data": {
    "searchPatients": [
      {
        "id": 1,
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com"
      },
      {
        "id": 2,
        "firstName": "Johnny",
        "lastName": "Smith",
        "email": "johnny.smith@example.com"
      }
    ]
  }
}

If you receive an error, check:

  • Your JWT token is correctly set
  • The Authorization header is included with Bearer scheme
  • The app header is set to "api"
  • Your request is using POST method
  • The Content-Type is set to application/json

Step 4: Explore More Operations​

Now that you're connected, try these common operations:

Create an External Patient​

import { graphql } from '@/gql/gql';

export const CreateExternalPatientMutation = graphql(`
  mutation CreateExternalPatient($input: CreateExternalPatientInput!) {
    createExternalPatient(input: $input) {
      patientId
      message
      success
    }
  }
`);

Check Appointment Availability​

import { graphql } from '@/gql/gql';

export const CheckAvailabilityQuery = graphql(`
  query CheckAvailability(
    $locationId: uuid!
    $serviceIds: [uuid]!
    $time: String!
    $providerId: uuid!
  ) {
    checkAvailability(
      locationId: $locationId
      serviceIds: $serviceIds
      time: $time
      providerId: $providerId
    ) {
      isAvailable
      errors
      __typename
    }
  }
`);

Get Provider Information​

query GetProvider($id: uuid!) {
  provider_by_pk(id: $id) {
    id
    firstName
    lastName
  }
}

Step 5: Use GraphQL Features​

Variables​

Instead of hardcoding values, use variables:

query GetPatientById($id: uuid!) {
  patient_by_pk(id: $id) {
    id
    firstName
    lastName
    email
    phoneNumber
  }
}

With variables:

{
  "id": 123
}

Fragments​

Reuse common field selections:

fragment PatientBasicInfo on patient {
  id
  firstName
  lastName
  email
}

query searchPatientsWithFragment {
  searchPatients(args: { search: "smith" }) {
    ...PatientBasicInfo
    dateOfBirth
  }
}

Aliases​

Query multiple providers in one request:

query GetMultipleProviders {
  provider1: provider_by_pk(id: 1) {
    firstName
    lastName
    specialty
  }
  provider2: provider_by_pk(id: 2) {
    firstName
    lastName
    specialty
  }
}

Common Issues and Solutions​

Authentication Error​

{
  "errors": [{
    "message": "Authorization header is missing or invalid"
  }]
}

Solution: Ensure your JWT token is correctly set in the Authorization header with Bearer scheme and the app header is set to "api".

Rate Limiting​

{
  "errors": [{
    "message": "Rate limit exceeded"
  }]
}

Solution: Implement exponential backoff or reduce request frequency.

Invalid Query​

{
  "errors": [{
    "message": "field 'invalidField' not found in type 'patient'"
  }]
}

Solution: Check the GraphQL Schema for valid field names.

What's Next?​

Need Help?​