Sigma v1 REST API API Reference

The Sigma API 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 view your Org's private Merits and act on behalf of your Org.

You can choose to make your App "linkable" which allows you to prompt other Orgs to allow your App to act on their behalves.

Your App can use Sigma Connect to have Sigma Users share their public profiles and Merits with it or one of the Orgs its acting on behalf of.

Nearly all endpoints are open to all Apps but API responses may change depending on which Org you're acting as and how your App is configured. In particular, different Apps and AppLinks will see more or fewer Merits in responses based on their identity and configured permissions, and most actions that create or modify Merits or other data can only be taken by Apps and AppLinks with appropriate permissions.

To get started, you'll 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

Authentication

Basic Auth

Each App has one or more secure authentication tokens that can be used to authenticate requests as the App. When an authentication token is created (either when the App is created or later) you are given a secret string. You can use the authentication token by base64-encoding the concatenation of your App ID, a colon, and the secret then passing it in the "Authorization" header as "Basic base64string".

Authorization: Basic base64Encode($appId:$secret)

type
basic

Bearer Auth

Each AppLink has a secure token that can be used to authenticate requests as the AppLink. To generate an AppLink token, you need to be authenticated as an App and do POST /applinks/{applinkId}/generateToken , which will respond with an appLink authentication token, which you can then pass as a Bearer Token.

Authorization: Bearer $token

type
bearer

orgs

Official organizations, associations, institutions, clubs, and groups are called Orgs in Sigma. They're created 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.

create org

POST /orgs/create

Create an Org. This Org will be unverified until Sigma reviews the Org by reaching out to the contact info supplied on creation. The Org will be able to create MeritTemplates and send merits but users will not receive the merits until the Org is verified.

orgTitle: string

The title of the org. If the title exists then a duplicate org error will be returned

website: string

The url of the Org's website.

phoneInfo: PhoneInfo

The country code and reachable phone number of the Org.

firstName: string

The first name of the Admin of the new Org

lastName: string

The last name of the Admin of the new Org

email: string

The contact email of the admin of the Org. If no Sigma User with this email exists one will be created.

positionAtOrg: string

The position of the admin of the new Org

Request Example
{
  "orgTitle": "string",
  "website": "string",
  "phoneInfo": {
    "countryCode": "string",
    "phoneNumber": "long"
  },
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "positionAtOrg": "string"
}
200 OK
Org

ok

404 Not Found

no such Org

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "title": "string",
  "description": "string",
  "website": "string",
  "email": "string",
  "phoneInfo": {
    "countryCode": "string",
    "phoneNumber": "long"
  },
  "addressInfo": {
    "addressString": "string"
  },
  "timezone": "string"
}

get org by id

GET /orgs/{orgId}

Given an Org ID, get the corresponding Org object.

orgId
in path
string

(no description)

200 OK
Org

ok

404 Not Found

no such Org

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "title": "string",
  "description": "string",
  "website": "string",
  "email": "string",
  "phoneInfo": {
    "countryCode": "string",
    "phoneNumber": "long"
  },
  "addressInfo": {
    "addressString": "string"
  },
  "timezone": "string"
}

get merittemplates by org

GET /orgs/{orgId}/merittemplates

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

orgId
in path
string

(no description)

200 OK

ok

404 Not Found

no such Org

Response Content-Types: application/json
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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  }
]

create merittemplate

POST /orgs/{orgId}/merittemplates/create

Given an Org ID and Merit Template Information, create a MeritTemplates the Org has created.

title: string

The title of the meritTemplate. If the title exists then a duplicate merit error will be returned

shortDescription: string

A short description of the meritTemplate.

whatItRepresentsDescription: string

A description of what the merit represent

howToEarnDescription: string

A description of the process or qualifications needed to earn this merit

meritCategoryId: string

An Id for the meritCategory to place the MeritTemplate in All merits must be placed in a merit category

permanentlyHidden: boolean

Whether this MeritTemplate will show up as hidden on a Users page. Other Users will not be able to see, nor can the receiving user unhide it.

customFieldTitles: string[]

Titles for the values stored in the custom fields of the Merit.

string
orgId
in path
string

(no description)

Request Example
{
  "title": "string",
  "shortDescription": "string",
  "whatItRepresentsDescription": "string",
  "howToEarnDescription": "string",
  "meritCategoryId": "string",
  "permanentlyHidden": "boolean",
  "customFieldTitles": [
    "string"
  ]
}
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",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "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
in path
string

(no description)

200 OK

ok

404 Not Found

no such MeritTemplate

Response Content-Types: application/json
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",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "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
in path
string

(no description)

first
in query
int 10

(no description)

after
in query
string

(no description)

200 OK

ok

type
404 Not Found

no such MeritTemplate

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "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"
    },
    "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",
        "email": "string",
        "phoneInfo": {
          "countryCode": "string",
          "phoneNumber": "long"
        },
        "addressInfo": {
          "addressString": "string"
        },
        "timezone": "string"
      }
    },
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    },
    "user": {
      "id": "string",
      "claimedProfile": "boolean",
      "name": {
        "firstName": "string",
        "lastName": "string"
      }
    }
  }
]

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” or "Unapproved" depending on the value of the preapprove parameter. If the Org corresponding to the MeritTemplate used is unverified, the new Merit’s status will be "Unverified” or "UnapprovedUnverified" depending on the value of the preapprove parameter.

email: string

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

issuedToName: 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.

preapprove: boolean

Determines Merit's status. "Pending" on true, otherwise "Unapproved" for verified Org. "Unverified” on true, otherwise "UnapprovedUnverified" for unverified Org.

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

ok

404 Not Found

no such MeritTemplate

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

get merittemplates by org

GET /orgs/{orgId}/merittemplates

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

orgId
in path
string

(no description)

200 OK

ok

404 Not Found

no such Org

Response Content-Types: application/json
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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  }
]

create merittemplate

POST /orgs/{orgId}/merittemplates/create

Given an Org ID and Merit Template Information, create a MeritTemplates the Org has created.

title: string

The title of the meritTemplate. If the title exists then a duplicate merit error will be returned

shortDescription: string

A short description of the meritTemplate.

whatItRepresentsDescription: string

A description of what the merit represent

howToEarnDescription: string

A description of the process or qualifications needed to earn this merit

meritCategoryId: string

An Id for the meritCategory to place the MeritTemplate in All merits must be placed in a merit category

permanentlyHidden: boolean

Whether this MeritTemplate will show up as hidden on a Users page. Other Users will not be able to see, nor can the receiving user unhide it.

customFieldTitles: string[]

Titles for the values stored in the custom fields of the Merit.

string
orgId
in path
string

(no description)

Request Example
{
  "title": "string",
  "shortDescription": "string",
  "whatItRepresentsDescription": "string",
  "howToEarnDescription": "string",
  "meritCategoryId": "string",
  "permanentlyHidden": "boolean",
  "customFieldTitles": [
    "string"
  ]
}
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",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "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
in path
string

(no description)

200 OK

retrieved Merit

404 Not Found

no such Merit

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "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
in path
string

(no description)

first
in query
int 10

(no description)

after
in query
string

(no description)

200 OK

ok

type
404 Not Found

user not found

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "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"
    },
    "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",
        "email": "string",
        "phoneInfo": {
          "countryCode": "string",
          "phoneNumber": "long"
        },
        "addressInfo": {
          "addressString": "string"
        },
        "timezone": "string"
      }
    },
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    },
    "user": {
      "id": "string",
      "claimedProfile": "boolean",
      "name": {
        "firstName": "string",
        "lastName": "string"
      }
    }
  }
]

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
in path
string

The ID of the Merit to approve

200 OK

updated Merit

404 Not Found

no such Merit

409 Conflict

was already approved

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

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)
newSuspended: boolean
preapprove: boolean

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

meritId
in path
string

The ID of the Merit to modify

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

updated Merit

404 Not Found

no such Merit

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

reject unapproved merit

POST /merits/{meritId}/reject

Given a Merit ID corresponding to a Merit with status "Unapproved", reject the Merit.

meritId
in path
string

The ID of the Merit to reject

200 OK

updated Merit

404 Not Found

no such Merit

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

revoke a merit

POST /merits/{meritId}/revoke

Given a Merit ID, change the corresponding Merit's status to Revoked.

reason: string

A description of why this Merit is being revoked.

preapprove: boolean

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

meritId
in path
string

The ID of the Merit to revoke

Request Example
{
  "reason": "string",
  "preapprove": "boolean"
}
200 OK

updated Merit

404 Not Found

no such Merit

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "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
in path
string

(no description)

first
in query
int 10

(no description)

after
in query
string

(no description)

200 OK

ok

type
404 Not Found

no such MeritTemplate

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "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"
    },
    "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",
        "email": "string",
        "phoneInfo": {
          "countryCode": "string",
          "phoneNumber": "long"
        },
        "addressInfo": {
          "addressString": "string"
        },
        "timezone": "string"
      }
    },
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    },
    "user": {
      "id": "string",
      "claimedProfile": "boolean",
      "name": {
        "firstName": "string",
        "lastName": "string"
      }
    }
  }
]

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” or "Unapproved" depending on the value of the preapprove parameter. If the Org corresponding to the MeritTemplate used is unverified, the new Merit’s status will be "Unverified” or "UnapprovedUnverified" depending on the value of the preapprove parameter.

email: string

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

issuedToName: 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.

preapprove: boolean

Determines Merit's status. "Pending" on true, otherwise "Unapproved" for verified Org. "Unverified” on true, otherwise "UnapprovedUnverified" for unverified Org.

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

ok

404 Not Found

no such MeritTemplate

Response Content-Types: application/json
Response Example (200 OK)
{
  "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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

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.

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
in path
string

(no description)

first
in query
int 10

(no description)

after
in query
string

(no description)

200 OK

ok

type
404 Not Found

user not found

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "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"
    },
    "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",
        "email": "string",
        "phoneInfo": {
          "countryCode": "string",
          "phoneNumber": "long"
        },
        "addressInfo": {
          "addressString": "string"
        },
        "timezone": "string"
      }
    },
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    },
    "user": {
      "id": "string",
      "claimedProfile": "boolean",
      "name": {
        "firstName": "string",
        "lastName": "string"
      }
    }
  }
]

get user by id

GET /users/{userId}

Given a User ID, get the corresponding User object.

userId
in path
string

(no description)

200 OK

ok

404 Not Found

no such User

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "claimedProfile": "boolean",
  "name": {
    "firstName": "string",
    "lastName": "string"
  }
}

form a Sigma Connect connection

POST /users/connect

Given a token acquired through the Sigma Connect web flow, forms a connection between the corresponding User and the authenticated App or AppLink and returns the User's ID.

token
in query
string

A Sigma Connect token

200 OK
ID

ok

Response Content-Types: application/json
Response Example (200 OK)
"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.

create applink

POST /applinks/create?token=$token

Given an AppLink ID, get the corresponding AppLink object.

applinkId
in path
string

(no description)

token
in query string
string

The JWT generated when App is linked to Org (taken from URL)

200 OK

ok

404 Not Found

no such AppLink

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "app": {
    "id": "string",
    "title": "string",
    "org": {
      "id": "string",
      "title": "string",
      "description": "string",
      "website": "string",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "linkedOrg": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  }
}

get app by id

GET /apps/{appId}

Given an App ID, get the corresponding App object.

appId
in path
string

(no description)

200 OK
App

ok

404 Not Found

no such App

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "title": "string",
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  }
}

Schema Definitions

ID: string

IssuedToName:

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

UserName:

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

PhoneInfo:

countryCode: string
phoneNumber: long
Example
{
  "countryCode": "string",
  "phoneNumber": "long"
}

LatitudeLongitude:

latitude: double
longitude: double
Example
{
  "latitude": "double",
  "longitude": "double"
}

AddressInfo:

addressString: string
Example
{
  "addressString": "string"
}

User:

An object representing a Sigma User

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

Org:

id: ID
title: string
description: string
website: string
email: string
phoneInfo: PhoneInfo
addressInfo: AddressInfo
timezone: string
Example
{
  "id": "string",
  "title": "string",
  "description": "string",
  "website": "string",
  "email": "string",
  "phoneInfo": {
    "countryCode": "string",
    "phoneNumber": "long"
  },
  "addressInfo": {
    "addressString": "string"
  },
  "timezone": "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 first became visible to the User it was sent to. If the Org is unverified or the Merit is not approved this field is not set.

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.

string
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"
  },
  "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",
      "email": "string",
      "phoneInfo": {
        "countryCode": "string",
        "phoneNumber": "long"
      },
      "addressInfo": {
        "addressString": "string"
      },
      "timezone": "string"
    }
  },
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  },
  "user": {
    "id": "string",
    "claimedProfile": "boolean",
    "name": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

MeritTemplate:

id: ID
title: string
shortDescription: string
howToEarnDescription: string
whatItRepresentsDescription: string
customFieldTitles: string[]
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",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  }
}

App:

An object representing an App

id: ID
title: string
org: Org
Example
{
  "id": "string",
  "title": "string",
  "org": {
    "id": "string",
    "title": "string",
    "description": "string",
    "website": "string",
    "email": "string",
    "phoneInfo": {
      "countryCode": "string",
      "phoneNumber": "long"
    },
    "addressInfo": {
      "addressString": "string"
    },
    "timezone": "string"
  }
}