Create Invitation

Create an invitation to link external references to a new or existing user.

Endpoint

POST /v1/invitations

Authentication

Required Scopes: pearsana-partner/partners.invitations:write and pearsana-partner/partners.externalRefs:write

Both scopes required

This endpoint requires two scopes. Make sure both are enabled on your App Client and included in your token request.

Headers

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

Request Body

{
	"externalReferences": [
		{
			"namespace": "SIS",
			"externalId": "STU-2024-001"
		}
	],
	"email": "student@example.com",
	"identity": {
		"firstName": "Jane",
		"lastName": "Smith"
	},
	"message": "Welcome to Pearsana!",
	"roles": ["student"]
}

Request Parameters

External References Array (Required)

Minimum 1 entry required. Namespaces must be unique within the request.

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

Identity Object (Required)

Field	Type	Required	Description
firstName	string	Yes	First name
lastName	string	Yes	Last name

Other Fields

Field	Type	Required	Description
email	string	Yes	Valid email address
message	string	No	Custom invitation message
roles	array	No	User roles (default: ["student"])

Response

Success Response

Status Code: 201 Created

{
	"invitation": {
		"invitationId": "inv_abc123xyz",
		"status": "pending",
		"userState": "new",
		"creationDateTime": "2026-01-30T12:00:00.000Z"
	}
}

Field	Type	Description
invitationId	string	Unique invitation identifier
status	string	pending, accepted, or expired
userState	string	new (user created) or existing (user already existed)
creationDateTime	string	ISO 8601 timestamp

Error Responses

400 Validation Error

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Validation failed",
		"details": {
			"errors": ["externalReferences is required and must be a non-empty array", "email 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.invitations:write",
				"pearsana-partner/partners.externalRefs:write"
			],
			"providedScopes": ["pearsana-partner/partners.invitations:write"]
		},
		"requestId": "abc-123-def"
	}
}

409 External Reference Conflict

Returned when the external reference is already linked to another user in your organisation.

{
	"error": {
		"code": "EXTERNAL_REF_CONFLICT",
		"message": "External reference SIS/STU-2024-001 is already linked to another user in this organisation.",
		"details": {
			"type": "SIS",
			"externalId": "STU-2024-001"
		},
		"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/invitations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-01-30" \
  -d '{
    "externalReferences": [
      {
        "namespace": "SIS",
        "externalId": "STU-2024-001"
      }
    ],
    "email": "student@example.com",
    "identity": {
      "firstName": "Jane",
      "lastName": "Smith"
    },
    "message": "Welcome to Pearsana! Click to verify your account.",
    "roles": ["student"]
  }'

Validation Rules

• Email format — must be a valid email address
• External references — must contain at least one entry
• Unique namespaces — external reference namespaces must be unique within the request
• No conflicts — external references cannot already be linked to another user in the organisation
• Email normalisation — email addresses are converted to lowercase
• Namespace normalisation — namespaces are converted to lowercase
• External ID trimming — external IDs are trimmed of whitespace

Invitation Workflow

1. Create invitation — POST /v1/invitations
2. User receives email — invitation email sent to the specified address
3. User accepts — user clicks the link and verifies their account
4. Status updates — invitation status changes from pending to accepted
5. External references linked — user account is linked to all specified external references