Create User

Create a new user in your organisation with optional profile information.

Endpoint

POST /v1/users

Authentication

Required Scope: pearsana-partner/partners.users:write

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
X-API-Version: 2026-01-30

Request Body

Minimal Request

{
	"identity": {
		"email": "student@example.com",
		"firstName": "Jane",
		"lastName": "Smith",
		"roleName": "student"
	},
	"externalReferences": [
		{
			"namespace": "SIS",
			"externalId": "STU-2024-001"
		}
	]
}

Full Request with Profile

{
	"identity": {
		"email": "student@example.com",
		"firstName": "Jane",
		"lastName": "Smith",
		"roleName": "student"
	},
	"externalReferences": [
		{
			"namespace": "SIS",
			"externalId": "STU-2024-001"
		},
		{
			"namespace": "PEARSANA",
			"externalId": "PEARSANA-123456"
		}
	],
	"profile": {
		"preferredName": "Jane",
		"phone": "+1-555-123-4567",
		"currency": "USD",
		"address": {
			"line1": "123 University Ave",
			"line2": "Apt 4B",
			"city": "Boston",
			"state": "MA",
			"zip": "02134",
			"country": "United States",
			"dateOfBirth": "2000-05-15",
			"citizenship": "United States"
		}
	}
}

Request Parameters

Identity Object (Required)

Field	Type	Required	Description
email	string	Yes	Valid email address
firstName	string	Yes	First name
lastName	string	Yes	Last name
roleName	string	Yes	User role (e.g. "student", "faculty")

External References Array (Required)

Minimum 1 entry required.

Field	Type	Required	Description
namespace	string	Yes	System namespace (e.g. "SIS", "LMS", "PEARSANA")
externalId	string	Yes	External system identifier

Profile Object (Optional)

Field	Type	Description
preferredName	string	Preferred / display name
phone	string	Phone number
currency	string	Currency code (e.g. "USD", "GBP", "EUR")
address	object	Address information (see below)

Address Object (Optional)

Field	Type	Description
line1	string	Street address line 1
line2	string	Street address line 2
line3	string	Street address line 3
city	string	City
state	string	State / region
zip	string	Postal code
country	string	Country
dateOfBirth	string	Date of birth (YYYY-MM-DD)
citizenship	string	Citizenship country

Response

Success Response

Status Code: 201 Created

{
	"userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"email": "student@example.com",
	"organisationId": "org_abc123",
	"status": "created"
}

Field	Type	Description
userId	string	Unique user identifier
email	string	User's email address (normalised to lowercase)
organisationId	string	Organisation ID (derived from JWT)
status	string	Always "created" for successful requests

Error Responses

400 Validation Error

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Validation failed",
		"details": {
			"errors": ["identity.email is required", "identity.roleName is required"]
		},
		"requestId": "abc-123-def"
	}
}

401 Unauthorized

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Authentication required.",
		"requestId": "abc-123-def"
	}
}

403 Insufficient Scope

{
	"error": {
		"code": "INSUFFICIENT_SCOPE",
		"message": "Insufficient OAuth scopes for this operation.",
		"details": {
			"requiredScopes": ["pearsana-partner/partners.users:write"],
			"providedScopes": ["pearsana-partner/ping"]
		},
		"requestId": "abc-123-def"
	}
}

409 Duplicate Email

{
	"error": {
		"code": "CONFLICT",
		"message": "User with this email already exists",
		"details": {
			"userId": "existing-user-id",
			"email": "student@example.com"
		},
		"requestId": "abc-123-def"
	}
}

500 Internal Server Error

{
	"error": {
		"code": "INTERNAL_SERVER_ERROR",
		"message": "An unexpected error occurred.",
		"requestId": "abc-123-def"
	}
}

Example Request

curl -X POST https://sandbox.api.pearsana.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-01-30" \
  -d '{
    "identity": {
      "email": "student@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "roleName": "student"
    },
    "externalReferences": [
      {
        "namespace": "SIS",
        "externalId": "STU-2024-001"
      }
    ]
  }'