Sigma v1 REST API API Reference

Sigma APIs allow you to integrate with our systems in a variety of ways. We are actively developing more. Reach out to us at dev@sig.ma with questions or feedback.

To use the Sigma REST API you'll create an "App" which can be linked by your own Org or by other Orgs. Each API call you make will be on behalf of an Org that's linked the App — either your own Org or a third-party one. API responses may change depending on which Org you're acting as.

To get started, you will first need a Sigma Org. If you don’t have a Sigma Org, create one here. Once you’ve done so, email us at dev@sig.ma and we’ll create your App and send you your authentication token so that you can start developing.

API Endpoint
https://api.sig.ma/v1
Contact: dev@sig.ma
Schemes: https
Version: v1

orgs

Official organizations, associations, institutions, clubs, and groups are called Orgs in Sigma. They're created using using the Sigma web app. Before they can interact with the outside world using Sigma they must be verified as real by Sigma, but they're immediately able to use the Sigma Admin Dashboard and link Apps to build their page and create MeritTemplates.

Orgs can currently only be created via the Sigma web app and modified via the Sigma Admin Dashboard.

get org by id

GET /orgs/{orgId}

Given an Org ID, get the corresponding Org object.

orgId

(no description)

type
string
in
path
200 OK
Org

ok

404 Not Found

no such Org

Response Example (200 OK)
{
  "id": "string",
  "title": "string",
  "description": "string",
  "website": "string",
  "phoneCountryCode": "string",
  "phoneNumber": "string"
}

get merittemplates by org

GET /orgs/{orgId}/merittemplates

Given an Org ID, get all MeritTemplates the Org has created.

orgId

(no description)

type
string
in
path
200 OK

ok

404 Not Found

no such Org

Response Example (200 OK)
[
  {
    "id": "string",
    "title": "string",
    "shortDescription": "string",
    "howToEarnDescription": "string",
    "whatItRepresentsDescription": "string",
    "customFieldTitles": [
      "string"
    ],
    "permanentlyHidden": "boolean",
    "archived": "boolean",
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "phoneCountryCode": "string",
      "phoneNumber": "string"
    }
  }
]

merittemplates

Orgs on Sigma create MeritTemplates which represent certificates, licenses, membership cards, trophies, badges, and more. MeritTemplates are displayed on the Org's page on Sigma.

Orgs can currently only be created and modified via the Sigma Admin Dashboard, but that functionality is coming to the API soon.

get merittemplate by id

GET /merittemplates/{meritTemplateId}

Given a MeritTemplate ID, get the corresponding MeritTemplate object.

meritTemplateId

(no description)

type
string
in
path
200 OK

ok

404 Not Found

no such MeritTemplate

Response Example (200 OK)
{
  "id": "string",
  "title": "string",
  "shortDescription": "string",
  "howToEarnDescription": "string",
  "whatItRepresentsDescription": "string",
  "customFieldTitles": [
    "string"
  ],
  "permanentlyHidden": "boolean",
  "archived": "boolean",
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "phoneCountryCode": "string",
    "phoneNumber": "string"
  }
}

get merits by merittemplate

GET /merittemplates/{meritTemplateId}/merits

Given a MeritTemplate's ID, look up existing Merits for the corresponding MeritTemplate. This will include public Merits and any other Merits the App is permitted to see.

meritTemplateId

(no description)

type
string
in
path
limit

(no description)

type
int 10
in
query
offset

(no description)

type
int 0
in
query
200 OK

ok

404 Not Found

no such MeritTemplate

Response Example (200 OK)
[
  null
]

send merit

POST /merittemplates/{meritTemplateId}/send

Send a Merit to an email address using a MeritTemplate. If the Org corresponding to the MeritTemplate used is verified the new Merit's status will be "Pending", otherwise it will be "Unverified" and will be held until the Org is verified, at which point it becomes "Pending" and the User is notified.

email: string

The email to send the Merit to. If no Sigma User with this email exists one will be created.

name: IssuedToName

The name of the individual you're sending the Merit to. Users can enter their own names, but this name will always be shown with the Merit.

customFieldValues: object

If the corresponding MeritTemplate has custom fields set you must include them here.

issueDateTime: datetime (ISO8601 string)
expirationDateTime: datetime (ISO8601 string)

If the corresponding MeritTemplate doesn't require an expiration date you cannot include one here.

Request Example
{
  "email": "string",
  "name": {
    "firstName": "string",
    "lastName": "string"
  },
  "customFieldValues": "object",
  "issueDateTime": "datetime (ISO8601 string)",
  "expirationDateTime": "datetime (ISO8601 string)"
}
200 OK

ok

404 Not Found

no such MeritTemplate

Response Example (200 OK)

propose sending a merit

POST /merittemplates/{meritTemplateId}/proposesend

Propose sending a Merit to an email address using a MeritTemplate. If the Org corresponding to the Merit is verified the new Merit's status will be "Unapproved", otherwise it will be "UnapprovedUnverified". It will be held until the Org is verified and the Merit is approved by an Org Admin or an App.

email: string

The email to send the Merit to. If no Sigma User with this email exists one will be created.

name: IssuedToName

The name of the individual you're sending the Merit to. Users can enter their own names, but this name will always be shown with the Merit.

customFieldValues: object

If the corresponding MeritTemplate has custom fields set you must include them here.

issueDateTime: datetime (ISO8601 string)
expirationDateTime: datetime (ISO8601 string)

If the corresponding MeritTemplate doesn't require an expiration date you cannot include one here.

Request Example
{
  "email": "string",
  "name": {
    "firstName": "string",
    "lastName": "string"
  },
  "customFieldValues": "object",
  "issueDateTime": "datetime (ISO8601 string)",
  "expirationDateTime": "datetime (ISO8601 string)"
}
200 OK

ok

Response Example (200 OK)

get merittemplates by org

GET /orgs/{orgId}/merittemplates

Given an Org ID, get all MeritTemplates the Org has created.

orgId

(no description)

type
string
in
path
200 OK

ok

404 Not Found

no such Org

Response Example (200 OK)
[
  {
    "id": "string",
    "title": "string",
    "shortDescription": "string",
    "howToEarnDescription": "string",
    "whatItRepresentsDescription": "string",
    "customFieldTitles": [
      "string"
    ],
    "permanentlyHidden": "boolean",
    "archived": "boolean",
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "phoneCountryCode": "string",
      "phoneNumber": "string"
    }
  }
]

merits

Merits are specific instances of MeritTemplates sent to individuals.

Sending and editing Merits can be done via the Sigma Admin Dashboard and the API.

get merit by id

GET /merits/{meritId}

Given a Merit ID, get the corresponding Merit object.

meritId

(no description)

type
string
in
path
200 OK

retrieved Merit

404 Not Found

no such Merit

Response Example (200 OK)

get merits by user

GET /users/{userId}/merits

Given a User's ID, look up their Merits. This will include the User's public Merits and any other Merits the App is permitted to see.

userId

(no description)

type
string
in
path
limit

(no description)

type
int 10
in
query
offset

(no description)

type
int 0
in
query
200 OK

ok

404 Not Found

user not found

Response Example (200 OK)
[
  null
]

approve merit by id

POST /merits/{meritId}/approve

Given a Merit ID, change the corresponding Merit's status from "Unapproved" to "Pending" or "UnapprovedUnverified" to "Unverified".

meritId

The ID of the Merit to approve

type
string
in
path
200 OK

updated Merit

404 Not Found

no such Merit

409 Conflict

was already approved

Response Example (200 OK)

edit a merit

POST /merits/{meritId}/edit

Given a Merit ID, change one or more fields on the corresponding Merit.

newIssuedToName: IssuedToName
newCustomFieldValues: object
newExpirationDateTime: datetime (ISO8601 string)
preapprove: boolean

If set to true the edit will skip the Approval Queue and be applied immediately.

meritId

The ID of the Merit to modify

type
string
in
path
Request Example
{
  "newIssuedToName": {
    "firstName": "string",
    "lastName": "string"
  },
  "newCustomFieldValues": "object",
  "newExpirationDateTime": "datetime (ISO8601 string)",
  "preapprove": "boolean"
}
200 OK

updated Merit

404 Not Found

no such Merit

Response Example (200 OK)

get merits by merittemplate

GET /merittemplates/{meritTemplateId}/merits

Given a MeritTemplate's ID, look up existing Merits for the corresponding MeritTemplate. This will include public Merits and any other Merits the App is permitted to see.

meritTemplateId

(no description)

type
string
in
path
limit

(no description)

type
int 10
in
query
offset

(no description)

type
int 0
in
query
200 OK

ok

404 Not Found

no such MeritTemplate

Response Example (200 OK)
[
  null
]

send merit

POST /merittemplates/{meritTemplateId}/send

Send a Merit to an email address using a MeritTemplate. If the Org corresponding to the MeritTemplate used is verified the new Merit's status will be "Pending", otherwise it will be "Unverified" and will be held until the Org is verified, at which point it becomes "Pending" and the User is notified.

email: string

The email to send the Merit to. If no Sigma User with this email exists one will be created.

name: IssuedToName

The name of the individual you're sending the Merit to. Users can enter their own names, but this name will always be shown with the Merit.

customFieldValues: object

If the corresponding MeritTemplate has custom fields set you must include them here.

issueDateTime: datetime (ISO8601 string)
expirationDateTime: datetime (ISO8601 string)

If the corresponding MeritTemplate doesn't require an expiration date you cannot include one here.

Request Example
{
  "email": "string",
  "name": {
    "firstName": "string",
    "lastName": "string"
  },
  "customFieldValues": "object",
  "issueDateTime": "datetime (ISO8601 string)",
  "expirationDateTime": "datetime (ISO8601 string)"
}
200 OK

ok

404 Not Found

no such MeritTemplate

Response Example (200 OK)

propose sending a merit

POST /merittemplates/{meritTemplateId}/proposesend

Propose sending a Merit to an email address using a MeritTemplate. If the Org corresponding to the Merit is verified the new Merit's status will be "Unapproved", otherwise it will be "UnapprovedUnverified". It will be held until the Org is verified and the Merit is approved by an Org Admin or an App.

email: string

The email to send the Merit to. If no Sigma User with this email exists one will be created.

name: IssuedToName

The name of the individual you're sending the Merit to. Users can enter their own names, but this name will always be shown with the Merit.

customFieldValues: object

If the corresponding MeritTemplate has custom fields set you must include them here.

issueDateTime: datetime (ISO8601 string)
expirationDateTime: datetime (ISO8601 string)

If the corresponding MeritTemplate doesn't require an expiration date you cannot include one here.

Request Example
{
  "email": "string",
  "name": {
    "firstName": "string",
    "lastName": "string"
  },
  "customFieldValues": "object",
  "issueDateTime": "datetime (ISO8601 string)",
  "expirationDateTime": "datetime (ISO8601 string)"
}
200 OK

ok

Response Example (200 OK)

users

When an Org sends a Merit or adds an admin a User is created for the corresponding email address if one doesn't exist yet. Once a Merit is ready to be accepted by the User they receive an email inviting them to "claim" their profile. You can look users up based on their email address or ID.

find user by email

GET /user/search

Given an email address, find a corresponding User if one exists.

email

the email address of the user you're searching for

type
string
in
query
200 OK

retrieved User

404 Not Found

no user with given email address

Response Example (200 OK)
{
  "id": "string",
  "claimedProfile": "boolean",
  "name": {
    "firstName": "string",
    "lastName": "string",
    "nickname": "string"
  }
}

get merits by user

GET /users/{userId}/merits

Given a User's ID, look up their Merits. This will include the User's public Merits and any other Merits the App is permitted to see.

userId

(no description)

type
string
in
path
limit

(no description)

type
int 10
in
query
offset

(no description)

type
int 0
in
query
200 OK

ok

404 Not Found

user not found

Response Example (200 OK)
[
  null
]

get user by id

GET /users/{userId}

Given a User ID, get the corresponding User object.

userId

(no description)

type
string
in
path
200 OK

ok

404 Not Found

no such User

Response Example (200 OK)
{
  "id": "string",
  "claimedProfile": "boolean",
  "name": {
    "firstName": "string",
    "lastName": "string",
    "nickname": "string"
  }
}

apps

Apps can currently only be created and modified by emailing dev@sig.ma, but that functionality is coming to the Sigma Admin Dashboard soon.

get app by id

GET /apps/{appId}

Given an App ID, get the corresponding App object.

appId

(no description)

type
string
in
path
200 OK
App

ok

404 Not Found

no such App

Response Example (200 OK)
{
  "id": "string",
  "title": "string",
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "phoneCountryCode": "string",
    "phoneNumber": "string"
  }
}

Schema Definitions

ID: string

IssuedToName:

firstName: string
lastName: string
Example
{
  "firstName": "string",
  "lastName": "string"
}

UserName:

firstName: string
lastName: string
nickname: string
Example
{
  "firstName": "string",
  "lastName": "string",
  "nickname": "string"
}

User:

An object representing a Sigma User

id: ID
claimedProfile: boolean
name: UserName
Example
{
  "id": "string",
  "claimedProfile": "boolean",
  "name": {
    "firstName": "string",
    "lastName": "string",
    "nickname": "string"
  }
}

Org:

id: ID
title: string
description: string
website: string
phoneCountryCode: string
phoneNumber: string
Example
{
  "id": "string",
  "title": "string",
  "description": "string",
  "website": "string",
  "phoneCountryCode": "string",
  "phoneNumber": "string"
}

merit:

An instance of a MeritTemplate issued by an Org to a User

id: ID
orgId: ID
meritTemplateId: ID
userId: ID
sendDateTime: datetime (ISO8601 string)

The time the Merit was created in Sigma. If the Org was verified after the Merit was created or the Merit required approval this may be before the time the Merit became visible to the User it was sent to.

issueDateTime: datetime (ISO8601 string)

The Merit’s “issue date” as specified by the Org.

expirationDateTime: datetime (ISO8601 string)

The Merit’s “expiration date” as specified by the Org. This is set if and only if the MeritTemplate this Merit corresponds to requires an expiration date.

expired: boolean

True if and only if the Merit has an expiration date and that date is before now.

suspended: boolean

True if and only if the Merit is suspended by the Org.

status: string Accepted, Pending, Reported, Revoked, Unapproved, UnapprovedUnverified, Unverified, Rejected

The Merit's current status

hidden: boolean

false by default. true if the user has explicitly requested it be hidden. Note that if the Merit doesn’t have a status of "Accepted" it will always be treated as hidden.

issuedToName: UserName
issuedToEmail: string

The email the Org used to send the Merit to.

customFieldValues: string[]

Values stored in the custom fields of the Merit.

merittemplate: MeritTemplate
org: Org
user: User
Example
{
  "id": "string",
  "orgId": "string",
  "meritTemplateId": "string",
  "userId": "string",
  "sendDateTime": "datetime (ISO8601 string)",
  "issueDateTime": "datetime (ISO8601 string)",
  "expirationDateTime": "datetime (ISO8601 string)",
  "expired": "boolean",
  "suspended": "boolean",
  "status": "string",
  "hidden": "boolean",
  "issuedToName": {
    "firstName": "string",
    "lastName": "string",
    "nickname": "string"
  },
  "issuedToEmail": "string",
  "customFieldValues": [
    "string"
  ],
  "merittemplate": {
    "id": "string",
    "title": "string",
    "shortDescription": "string",
    "howToEarnDescription": "string",
    "whatItRepresentsDescription": "string",
    "customFieldTitles": [
      "string"
    ],
    "permanentlyHidden": "boolean",
    "archived": "boolean",
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "phoneCountryCode": "string",
      "phoneNumber": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "phoneCountryCode": "string",
    "phoneNumber": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string",
      "nickname": "string"
    }
  }
}

MeritTemplate:

id: ID
title: string
shortDescription: string
howToEarnDescription: string
whatItRepresentsDescription: string
customFieldTitles: string[]
permanentlyHidden: boolean
archived: boolean
org: Org
Example
{
  "id": "string",
  "title": "string",
  "shortDescription": "string",
  "howToEarnDescription": "string",
  "whatItRepresentsDescription": "string",
  "customFieldTitles": [
    "string"
  ],
  "permanentlyHidden": "boolean",
  "archived": "boolean",
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "phoneCountryCode": "string",
    "phoneNumber": "string"
  }
}

App:

An object representing an App that Orgs can link

id: ID
title: string
org: Org
Example
{
  "id": "string",
  "title": "string",
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "phoneCountryCode": "string",
    "phoneNumber": "string"
  }
}