Back to home

Help Center

Integrations

Security and sign-on integrations

Enabling SCIM

Marq offer user provisioning/deprovisioning and group management via CRUD operations against the users and groups on an enterprise account via our SCIM API. To access the API, you must follow the steps below.

For a more detailed overview of SCIM, see Simple Cloud.

Enabling SCIM

Have an Enterprise subscription for Marq.
Enable automatic team upgrades (Team > Licensing, requires a role of Account Owner or Billing Admin).
Ensure SCIM has been enabled for your account (contact support for this).
Generate a SCIM bearer token (Team > App Integration > SCIM). This token is used to authenticate your requests.
Add the bearer token to your SCIM provider. Instructions for some are listed below:

SCIM Endpoints

All Marq SCIM endpoints start with the Marq base URL, which can be obtained on the same page as the SCIM bearer token (Team > App Integrations > SCIM):

Marq: https://users.app.marq.com/scim/v2/press

Bearer Token Authorization

Authorization is provided by using HTTP Authorization header, formed as such (using your own bearer token instead of the italicized example token shown):

Authorization: Bearer 1502c55ad68b4f3acdc969a7179a1313

Users

User Resource

{
   "id": string,
   "schemas": [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
     "urn:ietf:params:scim:schemas:extension:marq:1.0:User",
   ],
   "userName": string,
   "name": {
     "formatted": string, // givenName + " " + familyName
     "givenName": string,
     "familyName": string
   },    
   "displayName": string,
   "emails": [{
      "value": string, // email address
      "primary": boolean
   }],
   "active": boolean,
   "urn:ietf:params:scim:schemas:extension:marq:1.0:User": {
     "canEdit": boolean,
     "addOns": [string] 
   },
   "meta": {
     "resourceType": "User",
     "created": string, // ISO8601 DateTime 
     "lastModified": string, // ISO8601 DateTime 
     "version": string,
     "location": string // URI of user
   },
   "roles": [string]
}

“id” will be of the form “marq-1234” with 1234 being the ID of the Marq user
userName/displayName is usually the email address of the user
canEdit is the license status of the user
Marq users also have the following which contains the user’s smart fields:

"urn:ietf:params:scim:schemas:extension:marq:1.0:UserFields":{
    "website":"marq.com",
    "fullName":"John Doe",
    "address":"1324 Street\nSan Francisco, CA 94014",
    "title":"Engineer",
    "workPhone":"(888) 705-4096",
    "company":"Marq",
    "cellPhone":"(888) 705-4096",
    "logo":"https://dogtime.com/assets/uploads/2018/10/puppies-cover.jpg",
    "logo_1":"https://example.com/image_1.png",
    "secondaryLogo":"https://dogtime.com/assets/uploads/2018/10/puppies-cover.jpg",
    "secondaryLogo_1":"https://example.com/image_1.png",
    "tertiaryLogo":"https://dogtime.com/assets/uploads/2018/10/puppies-cover.jpg",
    "tertiaryLogo_1":"https://example.com/image_1.png",

For logos, it must be either "logo" for the key or "logo_" as a prefix for the key. For profile images, it is "profileImage" or a "profileImage_" prefix.
- If you want to use the secondary and tertiary profile image, use "secondaryProfileImage" and "tertiaryProfileImage".

     "logo_withAName":"https://example.com/image_2.png"
},

If you are in real estate and your agents have a license number tied to their property listings, you can use "agentNumber":

     "agentNumber": "00000000",
},

If you are connecting to Xpressdocs or your own printer, you will need to add the "User ID at Printer Vendor" and "Office ID at Print Vendor".

"urn:ietf:params:scim:schemas:extension:lucid:1.0:User": {

    "userIdAtPrintVendor": "00000000",

    "officeIdAtPrintVendor": "00000000",

    "billingCode": "00000000",
}

GET All Users

Get all users on an account.

URL - /Users

Optional Parameters

startIndex (number): index of first user in the list to return (1 indexed)
count (number): quantity of users to return from this request
filter (string): See SCIM spec and optimization details below.

Filtering

The only operator currently supported is “eq”
While filtering should technically work on every attribute of a user, it is a very slow process for non-optimized attributes. Filter only on the following optimized attributes whenever possible:

email / emails.value / workemail
username / displayname
externalid
canedit / urn:ietf:params:scim:schemas:extension:marq:1.0:user.canedit / urn:marq:schemas:1.0:user.canedit

Example : /Users?filter=email eq someEmail@example.com
Example : /Users?filter=urn:ietf:params:scim:schemas:extension:marq:1.0:user.canedit eq true

Response Body

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": number,
   "startIndex": number,
   "itemsPerPage": number,
   "Resources": [UserResource]
}

GET User

Get a specific user on the account

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Response Body

See UserResource

POST User

Create a new user

URL - /Users

Request Body

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "userName": string,
   "name": {
     "formatted": string (optional),
     "familyName": string (optional),
     "givenName": string (optional)
   },    
   "displayName": string (optional),
   "password": string (optional), // length must be at least 6 characters
   "emails": [{
      "value": string, // email address
      "type": string (optional),
      "primary": boolean (optional)
   }],
   "active": boolean (optional),
   "id": string (optional),
   "urn:ietf:params:scim:schemas:extension:marq:1.0:User": {
     "canEdit": boolean (optional),
     "addOns": [string] (optional) // valid addOns: “press-for-sales”
   } (optional),
   "roles": [string] (optional) 
}

Many parameters are marked as optional because they are not used in Marq’s system and will be ignored
password must be at least 6 characters in length (Marq password requirement)
Marq roles (“Team Admin”, “Billing Admin”, etc) that are listed in the roles field will be added to the user in Marq
addOns that are listed will give a user an addon license of the specified type

Response Body

See UserResource

PUT User

Modify an existing user

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Request Body

  {
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "userName": string,
   "name": {
     "formatted": string (optional),
     "familyName": string (optional),
     "givenName": string (optional)
   },    
   "displayName": string (optional),
   "password": string (optional), // length must be at least 6 characters
   "emails": [{
      "value": string, // email address
      "type": string (optional),
      "primary": boolean (optional)
   }],
   "active": boolean (optional),
   "id": string (optional),
  "urn:ietf:params:scim:schemas:extension:marq:1.0:User": {
     "canEdit": boolean (optional),
     "addOns": [string] (optional) // valid addOns: “press-for-sales”
   } (optional),
   "roles": [string] (optional) 
}

Will fail if attempting to update a user’s username or ID to a username or ID that already exist
All notes from POST User also apply
addOns will grant or leave any add-on licenses that are specified, and remove any licenses that the user has that are not specified. An empty list will remove all add-on licenses from the user. If no addOns field is specified, no change will be made to the user’s licenses

Response Body

See UserResource

PATCH User

Modify an existing user

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Request Body

 {
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:PatchOp"],
   "Operations": [
     {
       "op": string, // can be add, remove, or replace
       "path": string (optional),
       "value": JSON (optional) // object/array to be added/replaced
     }
   ]
}

See SCIM specification for more details
All notes from PUT User also apply

Response Body

See UserResource

DELETE User

Delete an existing user

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Response

204 No Content if delete was successful
404 Not Found if the user was not found

Groups

Group Resource

  {
   "id": string,
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "displayName": string,
   "members": [{
     "value": string, // id of group member
     "$ref": string, // URI of group member
     "display": string
   }],    
   "meta": {
     "resourceType": "Group",
     "created": string, // ISO8601 DateTime 
     "lastModified": string, // ISO8601 DateTime 
     "version": string,
     "location": string // URI of group
   }
}

“id” will be of the form “marq-group-1234” with 1234 being the ID of the Marq group

GET All Groups

Get all groups on an account.

URL - /Groups

Optional Parameters

startIndex (number): index of first group in the list to return (1 indexed)
count (number): quantity of groups to return from this request
filter (string): See SCIM spec (currently only the eq operator is supported)

Response Body

  {
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": number,
   "startIndex": number,
   "itemsPerPage": number,
   "Resources": [GroupResource]
}

GET Group

Get a specific group on the account

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Response Body

See GroupResource

POST Group

Create a new group

URL - /Groups

Request Body

 {
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "displayName": string,
   "members": [{
     "value": string, // id of group member
     "$ref": string (optional), // URI of group member
     "display": string (optional)
   }]
}

Parameters that are marked optional are ignored since attributes of a single member are immutable when using the Groups API

Response Body

See GroupResource

PUT Group

Modify an existing group

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Request Body

  {
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "displayName": string,
   "members": [{
     "value": string, //id of group member
     "$ref": string (optional), //URI of group member
     "display": string (optional)
   }]
}

All notes from POST Group also apply

Response Body

See GroupResource

PATCH Group

Modify an existing group

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Request Body

 {
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:PatchOp"],
   "Operations": [
     {
       "op": string, // can be add, remove, or replace
       "path": string (optional),
       "value": JSON (optional) // object/array to be added/replaced
     }
   ]
}

See SCIM specification for more details
All notes from PUT Group also apply

Response Body

See GroupResource

DELETE Group

Delete an existing group

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Response

204 No Content if delete was successful
404 Not Found if the group was not found