SSO Object v5

The following API calls are currently available for the SSO (Single Sign-On) object:

GET LIST - Get a list of all SSO integrations in your account.

https://restapi.surveygizmo.com/v5/sso

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True
pagepage=3False
resultsperpageresultsperpage=100False

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.surveygizmo.com/adfs/services/trust",
      "login": "https://example.surveygizmo.com/adfs/ls/",
      "logout": "https://example.surveygizmo.com/adfs/ls/",
      "cert_fingerprint": "abcd1234efgh5678ijkl9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-06-22 17:23:43",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "0",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.example.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.example.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

GET SSO - Get information about a specific SSO integration in your account.

https://restapi.surveygizmo.com/v5/sso/[SSOID]

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.
ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.surveygizmo.com/adfs/services/trust",
      "login": "https://example.surveygizmo.com/adfs/ls/",
      "logout": "https://example.surveygizmo.com/adfs/ls/",
      "cert_fingerprint": "1234abcd5678efgh9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-06-22 17:23:43",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "0",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.example.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.example.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

CREATE SSO - Set up SSO  in your account.

https://restapi.surveygizmo.com/v5/sso?_method=PUT&name=SurveyRespondentAuthentication&type=Account&entity_id=example&login=https://www.login.com&logout=https://www.logout.com&cert=-----BEGIN+CERTIFICATE-----%0D%0AMIagh%DCCBCCg-----END+CERTIFICATE-----

ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True
nameInternal Title (ex. Survey Respondent Authentication)True
typeAuthentication Type (Account, Survey)True
statusActive, ClosedFalse
entity_idThis is the globally-unique URL/string of your IdP entity.
True
loginLogin URLTrue
logoutLogout URLTrue
certThis is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer.
True
attributes[attribute name]Array of data attributes used with Survey Authentication Type (ex. attributes[Dept]=Sales)False
metadataurlIdentify Provider Metadata URL (allow SurveyGizmo to pull SAML settings from your IdP metadataFalse
userdisable0, 1, 2, etc. (Integer value indicating number of weeks of inactivity in SurveyGizmo before user is disabled)False
createuserstrue, false (if set to true, users are automatically created in SurveyGizmo)False
userroleRole IDFalse
userteamTeam IDFalse
userlicenseLicense ID*False
usersolotrue, falseFalse
notificationemailemail address (emails will be sent here in the event of errors when creating new users)False

*License IDs

LicenseID
Reporting19
Basic3
Standard14
HR Professional6
Market Research16
Educational20
Full Access7

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.surveygizmo.com/adfs/services/trust",
      "login": "https://example.surveygizmo.com/adfs/ls/",
      "logout": "https://example.surveygizmo.com/adfs/ls/",
      "cert_fingerprint": "1234abcd5678efgh9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-09-28 17:30:01",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "xxxxxx",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

UPDATE SSO - Update/Change SSO integration information.

https://restapi.surveygizmo.com/v5/sso/[SSOID]?_method=POST

ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True
nameInternal Title (ex. Survey Respondent Authentication)True
typeAuthentication Type (Account, Survey)True
statusActive, ClosedFalse
entity_idThis is the globally-unique URL/string of your IdP entity.
True
loginLogin URLTrue
logoutLogout URLTrue
certThis is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer.
True
attributes[attribute name]Array of data attributes used with Survey Authentication Type (ex. attributes[Dept]=Sales)False
metadataurlIdentify Provider Metadata URL (allow SurveyGizmo to pull SAML settings from your IdP metadataFalse
userdisable0, 1, 2, etc. (Integer value indicating number of weeks of inactivity in SurveyGizmo before user is disabled)False
createuserstrue, false (if set to true, users are automatically created in SurveyGizmo)False
userroleRole IDFalse
userteamTeam IDFalse
userlicenseLicense ID*False
usersolotrue, falseFalse
notificationemailemail address (emails will be sent here in the event of errors when creating new users)False

*License IDs

LicenseID
Reporting19
Basic3
Standard14
HR Professional6
Market Research16
Educational20
Full Access7

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.surveygizmo.com/adfs/services/trust",
      "login": "https://example.surveygizmo.com/adfs/ls/",
      "logout": "https://example.surveygizmo.com/adfs/ls/",
      "cert_fingerprint": "1234abcd5678efgh9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-09-28 17:30:01",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "xxxxxx",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

DELETE SSO - Delete specific SSO integration from your account.

https://restapi.surveygizmo.com/v5/domain/[DomainID]?_method=DELETE

ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345
True

Response Example (.json format):

{
  "result_ok": true,
  "status": "success"
}

Glossary of SSO Terms

 Active Directory Federated Services (AD FS)

Microsoft's IdP software.

 Entity ID

This is the globally unique URL/string of your IdP entity. It's like a mailing address that we, the service provider, use to contact your IdP.

Your Entity ID can be found in your AD FS Management Console by right-clicking the AD FS Folder and selecting Edit Federation Service Properties.

The URL in the Federation Service identifier field.

 Identity Provider (IdP)

The source of truth for usernames and passwords.

 Login URL

This is the URL for logging in to your IdP. The Login URL is often very similar to the Entity ID URL. This is where we will send the SAML request.

 Name ID

Unique string to identify users. When sending Name ID to SurveyGizmo we recommend it be their email address.

 Service Provider (SP)

The web-based application/s that are accessed via the IdP.

 Security Assertion Markup Language (SAML)

an XML standard that allows secure web domains to exchange user authentication and authorization data. Using SAML, an online service provider can contact a separate online identity provider to authenticate users who are trying to access secure content.

 Single Sign-On (SSO)

Provides partner companies with full control over the authorization and authentication of hosted user accounts that can access web-based applications.

 SSL Certificate

This is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer. NOTE:  If the file you have also has the ‘intermediate’ or ‘root’ certificate chains in them, that’s fine, as long as it has the main certificate for the domain included.

 User Principal Name (UPN)

The Name of the system user in email address format.