Profile Custom Fields API

Use profile custom fields to exchange organization-specific profile data through the Minerva Profiles API. Definitions belong to your organization and apply across all its workspaces. Requests use immutable definition keys, while responses include both keys and customer-facing labels. For administrator workflows, batch uploads, list columns, and profile views, see the Profile Custom Fields Guide.

This capability is not yet released to production. The Profiles API, dashboard stories, and this documentation are being prepared together. Do not deploy an integration until your Minerva technical contact confirms that the feature is available for your organization.

Prerequisites and key discovery

You need an application API key for the target organization and workspace. Send it in the x-api-key header. An administrator creates definitions under Administration > Configuration > Profile Custom Fields. Record each definition’s immutable key and, for Choice fields, each option’s stored value. Use keys in requests. Do not use labels as JSON property names because labels can be renamed.

x-api-key: YOUR_API_KEY

The examples below use https://api.gominerva.com/clm/v1. See the API Reference for authentication and generated endpoint pages.

Request contract

profileCustomFields is a JSON object whose property names are definition keys. Each value must use the JSON type required by that definition.

{
  "profileCustomFields": {
    "loan_number": "LN-2026-0042",
    "loan_status": "funded",
    "servicing_details": {
      "portfolio": "Prime",
      "boardingDate": "2026-08-27"
    }
  }
}

Use the object on these operations:

Operation	Behavior
`POST /profiles`	Creates a profile without an initial screen. All required custom fields must be present and non-null.
`POST /onboarding/profiles`	Creates and screens a profile. All required custom fields must be present and non-null.
`PATCH /profiles/{profileId}`	Updates only the custom keys supplied. Omitted custom keys are preserved. `null` clears one stored value.

On create or onboarding, null is equivalent to omitting an optional custom value and fails validation when the field is required. A PATCH validates the custom fields supplied in that request. Custom fields omitted from the request remain unchanged, and null clears one named value. Required custom fields that are not included are not checked again.

Writes use the latest definitions. An archived or unknown key, a wrong JSON type, an invalid Choice value, or an invalid Date returns HTTP 400. If Minerva cannot retrieve the definitions, it rejects the write instead of saving an unvalidated value. Fetch the latest definitions before sending values, and treat configuration changes as an integration contract change.

Type matrix

UI label	API `type`	Request JSON value	Example
Text	`text`	String	`"LN-2026-0042"`
Number	`number`	JSON number, integer or decimal	`4417723` or `12.75`
Date	`date`	String in `YYYY-MM-DD` format	`"2026-08-27"`
Yes/No	`boolean`	Boolean	`true`
Choice	`enum`	Configured stored option value	`"funded"`
Structured data	`json`	JSON object or array	`{"portfolio":"Prime"}`

Text values support up to 4,000 characters. Structured data must be an object or array and is limited to 16 KB per field. The combined custom values on one profile are limited to 64 KB. Exact integral Number values are accepted through the signed 64-bit range. Choice requests use the option’s stored value, such as funded, not its display label, such as Funded. After a Choice definition is saved, each existing option value remains valid and cannot be changed or removed in this release. Administrators can add options, change display labels, and reorder options. This preserves the identifiers already stored on profiles so historical values remain readable. If the vocabulary must be replaced, contact Minerva Support. Archiving the field and creating a new one is another option, but the new field starts empty and does not inherit existing profile values.

Create a profile

curl -X POST "https://api.gominerva.com/clm/v1/profiles" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Alex Morgan",
    "kind": "individual",
    "profileCustomFields": {
      "loan_number": "LN-2026-0042",
      "loan_status": "funded",
      "servicing_details": {
        "portfolio": "Prime",
        "boardingDate": "2026-08-27"
      }
    }
  }'

const response = await fetch("https://api.gominerva.com/clm/v1/profiles", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MINERVA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Alex Morgan",
    kind: "individual",
    profileCustomFields: {
      loan_number: "LN-2026-0042",
      loan_status: "funded",
      servicing_details: {
        portfolio: "Prime",
        boardingDate: "2026-08-27",
      },
    },
  }),
});

if (!response.ok) {
  const error = await response.text();
  throw new Error(`Minerva API returned ${response.status}: ${error}`);
}

const data = await response.json();
console.log(data.result.profile.id);

Create and screen a profile

Use POST /onboarding/profiles when profile creation should also perform the configured onboarding screen.

curl -X POST "https://api.gominerva.com/clm/v1/onboarding/profiles" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Alex Morgan",
    "kind": "individual",
    "profileCustomFields": {
      "loan_number": "LN-2026-0042",
      "loan_status": "funded",
      "servicing_details": {
        "portfolio": "Prime",
        "boardingDate": "2026-08-27"
      }
    }
  }'

const response = await fetch(
  "https://api.gominerva.com/clm/v1/onboarding/profiles",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.MINERVA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Alex Morgan",
      kind: "individual",
      profileCustomFields: {
        loan_number: "LN-2026-0042",
        loan_status: "funded",
        servicing_details: {
          portfolio: "Prime",
          boardingDate: "2026-08-27",
        },
      },
    }),
  },
);

if (!response.ok) {
  const error = await response.text();
  throw new Error(`Minerva API returned ${response.status}: ${error}`);
}

const data = await response.json();
console.log(data.result.profile.id, data.result.tasks);

Update or clear values

PATCH updates only the profile fields and custom field keys supplied in the request. Omitted custom fields remain unchanged, and null clears one named value.

cURL

curl -X PATCH \
  "https://api.gominerva.com/clm/v1/profiles/66c391b92888a0db5cc6d3f6" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "profileCustomFields": {
      "loan_status": "paid_out",
      "servicing_details": null
    }
  }'

This changes Loan Status, clears Servicing Details, and preserves Loan Number and every other custom value.

JavaScript

const profileId = "66c391b92888a0db5cc6d3f6";
const response = await fetch(
  `https://api.gominerva.com/clm/v1/profiles/${profileId}`,
  {
    method: "PATCH",
    headers: {
      "x-api-key": process.env.MINERVA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      profileCustomFields: {
        loan_status: "paid_out",
        servicing_details: null,
      },
    }),
  },
);

if (!response.ok) {
  throw new Error(`Minerva API returned ${response.status}`);
}

Response contract

Single-profile and list responses can include an optional profileCustomFields array. Items are ordered by definition priority.

Profile reads may take up to 60 seconds to reflect a definition edit or archive. During that period, GET /profiles/{profileId}, GET /profiles, and dashboard read views may return the prior field or Choice option label, or may still include a newly archived field. Stored profile values do not change. After the read view refreshes, renamed labels are updated and archived fields are omitted. Profile writes always validate against the latest definition.

{
  "msg": "OK",
  "result": {
    "profile": {
      "id": "66c391b92888a0db5cc6d3f6",
      "name": "Alex Morgan",
      "profileCustomFields": [
        {
          "key": "loan_number",
          "label": "Loan Number",
          "type": "text",
          "value": "LN-2026-0042"
        },
        {
          "key": "loan_status",
          "label": "Loan Status",
          "type": "enum",
          "value": "funded",
          "valueLabel": "Funded"
        },
        {
          "key": "servicing_details",
          "label": "Servicing Details",
          "type": "json",
          "value": {
            "portfolio": "Prime",
            "boardingDate": "2026-08-27"
          }
        }
      ]
    }
  },
  "status": 200
}

For Choice fields, value is the stable stored option value and valueLabel is the display label resolved for that response. Store or compare value; render valueLabel when present. After an administrator changes a field label or Choice option label, profile reads can return the previous label for up to 60 seconds. Profile writes always validate against the latest definition. The list operation returns the same optional array on each item:

{
  "msg": "OK",
  "result": {
    "profiles": [
      {
        "id": "66c391b92888a0db5cc6d3f6",
        "name": "Alex Morgan",
        "profileCustomFields": [
          {
            "key": "loan_number",
            "label": "Loan Number",
            "type": "number",
            "value": 9223372036854775807
          },
          {
            "key": "loan_status",
            "label": "Loan Status",
            "type": "enum",
            "value": "funded",
            "valueLabel": "Funded"
          }
        ]
      }
    ],
    "meta": {
      "page": 1,
      "perPage": 20,
      "total": 1
    }
  },
  "status": 200
}

Large integral Number values are emitted exactly as JSON numbers. JavaScript’s default JSON.parse rounds integers above Number.MAX_SAFE_INTEGER (9007199254740991). Use a lossless JSON parser before converting the response to JavaScript values. When a business identifier does not need arithmetic, define it as Text at the integration boundary instead. The Minerva API still requires a JSON number for fields whose definition type is Number.

Validation errors

The response follows the standard Minerva error shape, and the message identifies the custom field path when available. For profile writes, HTTP 400 means the request is malformed or a value does not match the current definition; correct the request before retrying. HTTP 409 means a Text value exceeds 4,000 characters, a Structured data value exceeds 16 KB, or the combined custom values exceed 64 KB; shorten the values before retrying. Separately, a definition-management request returns HTTP 409 if it omits or changes a saved Choice option value. Retain the complete saved Choice set, with any additions or label and order changes, before retrying that request. Common failures include:

Failure	Status	Example	Correction
Malformed JSON	400	Missing comma or closing brace	Correct the JSON document before retrying.
Unknown or archived key	400	`profileCustomFields.old_status`	Refresh active definitions and stop sending the retired key.
Wrong JSON type	400	`"amount": "125.50"` for Number	Send `125.50` as a JSON number.
Invalid Date	400	`"closing_date": "08/27/2026"`	Send `"2026-08-27"`.
Invalid Choice	400	`"loan_status": "Funded"`	Send the stored option value, such as `"funded"`.
Missing required value on create	400	`loan_number` omitted	Include a non-null value in create or onboarding.
Invalid Structured data	400	`"servicing_details": "Prime"`	Send a JSON object or array.
Text exceeds 4,000 characters	409	`loan_notes` has 4,001 characters	Shorten the Text value, then retry.
Structured data exceeds 16 KB	409	`servicing_details` exceeds 16 KB	Shorten the object or array, then retry.
Combined custom values exceed 64 KB	409	`profileCustomFields` exceeds 64 KB	Remove or shorten custom values, then retry.
Existing Choice value omitted	409	Definition update omits `funded`	Keep `funded`; change its label or order, and add new values when needed.

Example error handling:

JavaScript

const response = await fetch(
  "https://api.gominerva.com/clm/v1/profiles",
  options,
);

if (response.status === 400) {
  const error = await response.json();
  console.error(
    "Correct the profile custom field request before retrying",
    error,
  );
} else if (response.status === 409) {
  const error = await response.json();
  console.error(
    "Shorten the profile custom field values before retrying",
    error,
  );
} else if (!response.ok) {
  throw new Error(`Minerva API returned ${response.status}`);
}

Required-field rollout guidance

After a definition becomes required, the next profile create or onboarding request must include a valid non-null value. The change does not backfill existing profiles or make a PATCH fail when that required custom field is omitted. Supplied PATCH values still validate against the latest type, archive status, and Choice vocabulary. Before an administrator enables Required:

Inventory every profile creation path, including direct create, onboarding, CSV, and XLSX.
Update producers to send the immutable key with a correctly typed value.
Test missing, null, wrong-type, unknown-key, and archived-key requests.
Coordinate the activation time with the administrator.
Monitor HTTP 400 responses after activation. Prefer a forward edit that makes the field optional again. Historical rollback replays an old snapshot through current validation and can return HTTP 409 if it would omit a saved Choice value; see Archive, history, and rollback.

Optional is the safer default when not every source system has the value.

Backward compatibility

profileCustomFields is optional in both requests and responses. Existing clients can continue sending the old profile request shape. Responses omit the array when no stored values resolve to active definitions, preserving the previous response shape. Stored values are retained when a definition is archived. After the read view refreshes, archived definitions and values with no active definition are not emitted. Clients that deserialize with strict schemas should allow the optional array before the feature is enabled. Each array item contains key, label, type, and value; valueLabel is optional and is used for Choice fields.

Endpoint reference

Use the Profiles - Endpoints section of the API Reference for generated schemas and operation details:

Create Profile: POST /profiles
Create Profile (Onboarding): POST /onboarding/profiles
Update Profile: PATCH /profiles/{profileId}
Get Profile Details: GET /profiles/{profileId}
List profiles: GET /profiles

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Profile Custom Fields API

Prerequisites and key discovery

Request contract

Type matrix

Create a profile

Create and screen a profile

Update or clear values

Response contract

Validation errors

Required-field rollout guidance

Backward compatibility

Endpoint reference

​Prerequisites and key discovery

​Request contract

​Type matrix

​Create a profile

​Create and screen a profile

​Update or clear values

​Response contract

​Validation errors

​Required-field rollout guidance

​Backward compatibility

​Endpoint reference

Prerequisites and key discovery

Request contract

Type matrix

Create a profile

Create and screen a profile

Update or clear values

Response contract

Validation errors

Required-field rollout guidance

Backward compatibility

Endpoint reference