Loading ...

REST API: Add Persona | Axero Documentation

Home » axero documentation » Wiki » Documentation » REST API Overview » REST API: Users » REST API: Personas » REST API: Add Persona
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 31

REST API: Add Persona

0 
 /5
0 (0votes)
Open API Guide
POST/api/personas

Creates a persona from the name, conditions, and actions in the body, and returns the saved persona in ResponseData. A PersonaID above 0 in the body updates that persona instead of creating one.

Request

Request Header

HeaderRequiredValueDescription
AuthorizationYESBearer YOUR_TOKENBearer token for the authenticated user. Learn how to create Bearer tokens
Content-TypeYESapplication/jsonMust be set to application/json

Required Parameters

ParameterTypeRequiredLocationDescription
NameStringYESBodyName of the persona. Names do not have to be unique. A missing or empty name answers 200 with IsError true and Please enter a valid name.

Optional Parameters

ParameterTypeRequiredLocationDescription
PersonaIDIntegerNOBodyLeave it out, or send 0, to create a persona. A value above 0 updates that persona instead, the way Update Persona does: conditions and actions the body leaves out are removed. A value that is not a number is read as 0.
IsEnabledBooleanNOBodyWhether the persona is active. Defaults to false; a value that is not true or false is read as false.
IncludeActionsBooleanNOBodyWhether the persona's actions take their roles from SelectedRoles. When true, each action's RoleIDCSV is rebuilt from SelectedRoles. Defaults to false. A value that is not true or false, such as text, is read as false.
RunActionsOnSaveBooleanNOBodyWhen true and the persona is enabled, its actions run in the background right after the save. Defaults to false. A value that is not true or false, such as text, is read as false.
IsPrivateBooleanNOBodyMarks the persona as private. A private persona is visible only to people who can manage personas at the site level. When it targets a single space, people who can manage that space's personas can see it too. Defaults to false. A value that is not true or false, such as text, is read as false.
PersonaMatchConditionIntegerNOBody0 = Match all conditions, 1 = Match any condition. At the top level it sets how the condition groups combine. The same field on the first condition of a group sets how the conditions inside that group combine. The value is not checked: any other number is stored as sent. A value that is not a number, including a comma-separated list such as 1,2, is read as 0.
PersonaConditionsArrayNOBodyThe conditions a user must meet to match the persona. Each item carries the condition fields in the rows below. Left out, or sent as something other than a list, the persona is saved with no conditions and matches nobody.
ProfileFieldIDIntegerNOBodyThe profile field the condition compares, by the FieldUseID that Get Profile Fields returns. Left out, or sent as something other than a number, it is saved as 0, and the condition is still saved.
ConditionOperatorTypeIntegerNOBody0 = Equals, 1 = Does not equal, 2 = Contains, 3 = Does not contain, 4 = Begins with, 5 = Ends with, 6 = Less than or equal to, 7 = Less than, 8 = Equal to, 9 = Greater than, 10 = Greater than or equal to. Left out, or sent as something other than a number, it is read as 0 (Equals). A number outside the list is stored as sent, and the condition then matches users whatever their value. Check the value before you enable the persona.
ConditionValueStringNOBodyThe value compared against, as a string. For a pick-list field, send the ID of the chosen option (its OptionID in the field's options from Get Profile Fields). Left out, it is saved as an empty value. A JSON list instead of text is not read. It usually makes the whole body unreadable: the call answers 200 with IsError true (Required parameters are empty.) and nothing is saved. A one-item list in the last field of the body instead saves the persona without this condition.
ParentIDIntegerNOBody0 for the first condition of a group. A later condition in the same group carries the first condition's ConditionID, which exists only once the persona is saved. So on this call send 0, or leave it out: a condition with any other ParentID is dropped without an error. Add conditions to a group afterwards with Update Persona. A value that is not a number is read as 0.
GroupNameStringNOBodyLabel of the condition's group. A JSON list instead of text is not read. It usually makes the whole body unreadable: the call answers 200 with IsError true (Required parameters are empty.) and nothing is saved. A one-item list in the last field of the body instead saves the persona without this condition.
PersonaActionsArrayNOBodyWhat the persona does for the users who match. Each item carries the action fields in the rows below. Left out, or sent as something other than a list, the persona is saved with no actions.
ActionTypeIntegerNOBody1 = Add to space, 2 = Remove from space, 3 = Assign site role (the roles go in RoleIDCSV). Left out, or sent as something other than a number, it is saved as 0, which is none of the three types. A number outside the list is stored as sent.
ActionValueStringNOBodySpaceID to add the user to or remove the user from, for action types 1 and 2. For type 3, send an empty string. Every action needs one: an action without it answers 500 with an empty body, and the persona has already been saved without that action. The value is not checked here, so text that is not a space ID is stored as sent. A JSON list instead of text is not read. It usually answers 200 with IsError true (Required parameters are empty.) and saves nothing. A one-item list in the last field of the body instead saves the persona without this action.
RoleIDCSVStringNOBodyComma-separated role IDs for the action. For type 1 (Add to space), these are the space roles the user is given in that space. For type 3 (Assign site role), they are the site roles assigned. Sent inside each item of PersonaActions. When IncludeActions is true, this value is replaced by SelectedRoles, so send the roles there instead. The value is not checked on this call, so text that is not a list of role IDs is stored as sent. For an Add to space action, the persona then cannot be updated: Update Persona answers 500. Deleting it also answers 500, although the persona is deleted. A JSON list instead of text is not read. It usually answers 200 with IsError true (Required parameters are empty.) and saves nothing. A one-item list in the last field of the body instead saves the persona without this action.
SelectedRolesArrayNOBodyList of role IDs for the action, as strings. Used when IncludeActions is true: it replaces RoleIDCSV. Sent inside each item of PersonaActions. Numbers work as well as strings. A value that is not an array, such as a single string, is ignored, and the action is saved with no roles. With IncludeActions false it is ignored.

Example

Request Header

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request URL

https://your-site.com/api/personas

Request Body

{
"Name": "Human Resources",
    "IsEnabled": true,
    "IncludeActions": true,
    "PersonaMatchCondition": 0,
    "RunActionsOnSave": false,
    "PersonaConditions":
        [{
          "ProfileFieldID": 67,
          "ConditionValue": 611,
          "ConditionOperatorType": 0
        }],
    "PersonaActions":
        [{
          "ActionValue": "291",
          "ActionType": 1
        }]
}

Success Response

{
  "IsError": false,
  "ResponseMessage": "Changes saved successfully",
  "ResponseData": {
    "PersonaID": 8,
    "Name": "Human Resources",
    "CreatedBy": 42,
    "UpdatedBy": 42,
    "DateCreated": "2026-01-15T13:01:23.43",
    "LastUpdated": "2026-01-15T13:04:10.27",
    "IsEnabled": true,
    "IncludeActions": true,
    "IsPrivate": false,
    "PersonaMatchCondition": 0,
    "PersonaConditions": [
      {
        "ConditionID": 10,
        "PersonaID": 8,
        "ProfileFieldID": 67,
        "ConditionValue": "611",
        "CreatedBy": 42,
        "UpdatedBy": 42,
        "LastUpdated": "2026-01-15T13:04:10.27",
        "ConditionOperatorType": 0,
        "ParentID": 0,
        "PersonaMatchCondition": 0,
        "TenantID": 1
      }
    ],
    "PersonaActions": [
      {
        "ActionID": 4,
        "PersonaID": 8,
        "ActionValue": "291",
        "CreatedBy": 42,
        "UpdatedBy": 42,
        "LastUpdated": "2026-01-15T13:04:10.27",
        "ActionType": 1,
        "Index": 0,
        "TenantID": 1
      }
    ],
    "EditAbsoluteURL": "https://your-site.com/personas/addedit/8",
    "DateCreatedString": "01/15/2026",
    "LastUpdatedString": "01/15/2026",
    "RunActionsOnSave": false,
    "CreatedByUserDisplayName": "Jane Doe",
    "UpdatedByUserDisplayName": "Jane Doe",
    "TenantID": 1
  }
}

Error Response

{
  "IsError": true,
  "ResponseMessage": "Required parameters are empty."
}

Error Handling

Status CodeLikely CauseNext Action
400 Bad RequestNo request shape produces this status. A missing or unreadable body answers 200 with IsError and a required-parameters message; a text field sent as a JSON list usually makes the body unreadable.Verify the request payload against the required parameters.
401 UnauthorizedMissing or invalid Bearer token.Check token validity. Learn how to create Bearer tokens →
403 ForbiddenNo request produces this status. A caller who cannot manage personas gets 200 with IsError and You do not have sufficient permissions to perform this action.Read IsError on every response.
500 Server ErrorAn action has no ActionValue. The persona is saved without that action, and then the call fails with an empty body. Any other 500 is an internal failure.Send ActionValue in every action. Before retrying, look for the persona with Get Personas, because a retry creates a second one.

Rate Limits

While Axero does not enforce hard rate limits by default, we recommend the following best practices to ensure optimal performance:

  • Sustained Request Rate: Do not exceed 5 API calls per second
  • Sequential Processing: Wait for each request to complete before sending the next in automated workflows
  • Concurrent Connections: If parallel processing is required, limit to 3 or fewer simultaneous requests
  • Response Timeout: Ensure API responses complete within 15 seconds during testing

Axero may implement temporary rate restrictions if excessive API usage affects overall site performance. For high-volume integrations, contact Axero to discuss your requirements.

Wiki Index

Pages