Update a custom FHIR profile

PUT/fhir/profiles/{id}

Replaces an existing custom profile with a new StructureDefinition. The id path parameter is authoritative: if the StructureDefinition includes an id it must match the path parameter, and if it omits one the path parameter is used. The FHIR resource type of the profile cannot change. When implementation_guide is omitted, the profile keeps its existing implementation guide. A retained version string is allowed only when re-submitting the profile's current version with an unchanged StructureDefinition; otherwise it returns a conflict. While the profile has retained versions, its canonical URL cannot be changed.

RequiresBearerauthentication

Path parameters

idstringrequired

The lowercase StructureDefinition id of the custom profile.

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 updated

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.

PUTRequest

# 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 PUT "https://experiment.app.pheno.ml/fhir/profiles/custom-patient" \
  -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": "*"
        }
      ]
    }
  }
}'

200 OKExample 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"
}