Upload a custom FHIR profile

POST/fhir/profiles

Creates a custom profile from a FHIR StructureDefinition supplied as a JSON object. Metadata such as version, resource type, and url is read from the StructureDefinition; the lowercase StructureDefinition id becomes the profile's lookup key. When id is omitted, a random UUID is assigned. Optionally group the profile under a named implementation guide.

RequiresBearerauthentication

Body parameters

structure_definitionobjectrequired

A FHIR StructureDefinition as a JSON object. Must include url, type, and a snapshot with elements. Metadata such as version, resource type, and url is read from the StructureDefinition itself. The lowercase id becomes the profile's lookup key; when omitted, a random UUID is assigned.

implementation_guidestringoptional

Implementation Guide name to group this profile under. On create, defaults to "custom" if omitted; on update, omitting it preserves the profile's current guide. Cannot be "us_core" (reserved). Use this to organize custom profiles into named IGs that can be referenced when calling create/multi or document/multi endpoints.

Returns

Profile successfully created

Response fields

idstringrequired

The lowercase StructureDefinition id, used as the profile's lookup key.

sourcestringrequired

The profile's origin. Profile management responses return custom (uploaded) profiles, so this value is always "custom".

custombuiltin

resource_typestringrequired

The FHIR resource type from the StructureDefinition.

urlstringrequired

The canonical URL from the StructureDefinition.

versionstringrequired

The version from the StructureDefinition.version field.

statusstringoptional

The publication status from StructureDefinition.status. Expected FHIR values include draft, active, retired, and unknown; the server preserves authored strings.

datestringoptional

The authored publication date from StructureDefinition.date, when present. This is a FHIR dateTime string and may be less precise than a full timestamp.

canonicalstringrequired

The canonical profile reference, including the version pin when present.

fhir_versionstringrequired

The base FHIR version the StructureDefinition targets.

implementation_guidestringrequired

The implementation guide the profile belongs to.

created_atstring (date-time)required

updated_atstring (date-time)required

Last update timestamp for the profile's current StructureDefinition. For retained versions, this equals created_at.

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/fhir/profiles" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "implementation_guide": "acme-cardiology",
  "structure_definition": {
    "resourceType": "StructureDefinition",
    "id": "custom-patient",
    "url": "http://phenoml.com/fhir/StructureDefinition/custom-patient",
    "name": "CustomPatient",
    "status": "active",
    "fhirVersion": "4.0.1",
    "kind": "resource",
    "abstract": false,
    "type": "Patient",
    "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Patient",
    "derivation": "constraint",
    "snapshot": {
      "element": [
        {
          "id": "Patient",
          "path": "Patient",
          "min": 0,
          "max": "*"
        }
      ]
    }
  }
}'

201 CreatedExample Response

{
  "id": "custom-patient",
  "source": "custom",
  "resource_type": "Patient",
  "url": "http://phenoml.com/fhir/StructureDefinition/custom-patient",
  "version": "1.0.0",
  "status": "active",
  "date": "2026-08-24",
  "canonical": "http://phenoml.com/fhir/StructureDefinition/custom-patient|1.0.0",
  "fhir_version": "4.0.1",
  "implementation_guide": "acme-cardiology",
  "created_at": "2026-08-24T15:04:05Z",
  "updated_at": "2026-08-25T16:04:05Z"
}