Project $init | Medplum

On this page

The $init operation creates a new Medplum Project with an admin user in a single API call. Projects provide isolated environments for different applications, organizations, or tenants—each with their own users, access policies, and FHIR resources.

This operation streamlines the onboarding process for multi-tenant platforms, allowing you to programmatically provision new customer environments without manual setup steps.

Use Cases

• Customer Onboarding: Automatically create isolated project environments when new customers sign up
• Development Environments: Spin up separate projects for development, staging, and production
• Multi-Tenant SaaS: Provision tenant-specific projects with dedicated resources and access controls
• Testing and QA: Create temporary projects for automated testing scenarios
• Partner Integrations: Set up isolated environments for third-party integrations

Invoke the $init operation

[base]/Project/$init

For example:

curl 'https://api.medplum.com/fhir/R4/Project/$init' \

-X POST \

-H "Content-Type: application/fhir+json" \

-H "Authorization: Bearer MY_ACCESS_TOKEN" \

-d '{"resourceType":"Parameters", "parameter":[ {"name":"name", "valueString":"Test Project"} ]}'

Success Response

Example outcome:

{

"resourceType": "Project",

"id": "59aa86af-9673-4862-a441-5200e6163bfb",

"name": "Test Project",

"strictMode": true,

"owner": {

"reference": "User/eb0f26b9-1e42-4886-85fc-31919aeebc55"

}

}

Error Response

Example outcome when Project name not provided:

{

"resourceType": "OperationOutcome",

"id": "3820fda7-c6d4-4207-b597-90631f0881f9",

"issue": [\
\
    {\
\
      "severity": "error",\
\
      "code": "invalid",\
\
      "details": { "text": "Expected required input parameter 'name'" },\
\
      "expression": ["Parameters.parameter"]\
\
    }\
\
  ]

}

Assigning Project Ownership

By default, the API will attempt to use the User associated with the current access token as the Project owner. In cases where a different user should be the owner, or when the access token is not associated with a User, one can be manually assigned using a parameter: either owner for existing users, or ownerEmail to create the user.

curl 'https://api.medplum.com/fhir/R4/Project/$init' \

-X POST \

-H "Content-Type: application/fhir+json" \

-H "Authorization: Bearer MY_ACCESS_TOKEN" \

-d '{"resourceType":"Parameters", "parameter":[ {"name":"name", "valueString":"Test Project"}, \
\
    {"name":"owner", "valueReference": {"reference": "User/cb5bb36b-fcfa-4c07-8da1-5f3afd8d261d" } } ]}'