Invite a person

POST

/api/public/v1/invitations

curl --request POST \
  --url https://example.com/api/public/v1/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "Email": "example", "LastName": "example", "FirstName": "example", "MiddleName": "example", "Sphere": "SpInternal" }'

Invites one person by corporate email. If a record with that address already exists — in any status, archived included — nothing is created and the response reports its current state.

Authorizations

• ApiKey

Request Body^required

One person to invite. Creates an invitation, not a person — see the API overview.

object

Email

Corporate email. The matching key across systems; no separate external id exists.

string

LastName

string

FirstName

string

MiddleName

string

nullable

Sphere

string

Allowed values: SpInternal SpExternal

One person to invite. Creates an invitation, not a person — see the API overview.

object

Email

Corporate email. The matching key across systems; no separate external id exists.

string

LastName

string

FirstName

string

MiddleName

string

nullable

Sphere

string

Allowed values: SpInternal SpExternal

One person to invite. Creates an invitation, not a person — see the API overview.

object

Email

Corporate email. The matching key across systems; no separate external id exists.

string

LastName

string

FirstName

string

MiddleName

string

nullable

Sphere

string

Allowed values: SpInternal SpExternal

Responses

200

OK

Media typeapplication/json

What happened to one invitation. A record that already exists is reported here rather than rejected — bool InvitationResultDto.Created is false and EmployeeStatus InvitationResultDto.Status is the existing record’s current state.

object

Id

The employee record’s id, whether it was created now or already existed.

string

Email

string

Created

True when this call created the record; false when it already existed.

boolean

Status

string

Allowed values: NotActivated Invited Activated Revoked

InvitationSent

Whether this call sent an invitation email. A record that already existed answers false — nothing was sent — and can be reached with resend.

boolean

PortalUrl

Where this person’s card lives in the Portal. Opening it needs a signed-in Portal session — the link is an address, not access.

string

nullable

Example

{
  "Status": "NotActivated"
}

400

Bad Request

Media typeapplication/json

The Integration API’s error shape — RFC 7807 application/problem+json. The Portal API answers in its own { Error, Details } envelope because one client parses one shape; an external integrator expects the standard instead.

object

type

string

nullable

title

required

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Unauthorized

Media typeapplication/json

The Integration API’s error shape — RFC 7807 application/problem+json. The Portal API answers in its own { Error, Details } envelope because one client parses one shape; an external integrator expects the standard instead.

object

type

string

nullable

title

required

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}