This tutorial describes how to utilize the ETO Software API to authenticate and perform basic data operations. This quick start assumes no specific programming language or framework is leveraged. Basic understanding of ETO Software authentication (use of Single-Sign-On and staff accounts) and security contexts (Enterprise, Sites and Programs) is required.
The first series of calls made against the ETO Software API will be to authenticate and authorize a session against a specific enterprise, site and program.
Most of the calls necessary for authentication/authorization are preformed against the Security service. A list of the methods available can be seen by visiting https://services.etosoftware.ca/API/Security.svc/help.
Through the authentication process you will obtain several important tokens to be used in subsequent calls. They include:
Using a user’s Single-Sign-On credentials, authenticate against the API by making a POST with the user’s email address and passwords as a JSON object.
POST https://services.etosoftware.ca/API/Security.svc/SSOAuthenticate/
Content-Type: application/json
Accept: application/json
{"security":{"Email":"<email>","Password":"<Password>"}}
The response received should be in JSON format and contain an SSOAuthenticateResult object. The object should contain your AuthStatusCode (0 = success) and an SSOAuthToken.
{"SSOAuthenticateResult":
{"AccessKey":"00000000-0000-0000-0000-000000000000",
"AuthStatusCode":0,
"Email":"email@example.com",
"MarketplaceId":0,
"Password":"example",
"SSOAuthToken":"426330ef-2927-4f0d-b87a-398e54245c27",
"TimeZoneOffset":null
}
}
An ETO Single-Sign-On account could have access to multiple enterprises. To get a list of available enterprises, make a GET request to https://services.etosoftware.ca/API/Security.svc/GetSSOEnterprises/ with your SSO Auth Token as a parameter.
GET https://services.etosoftware.ca/API/Security.svc/GetSSOEnterprises/<authToken> Content-Type: application/json Accept: application/json
As a response, you should receive a JSON array of enterprises that your user account has access to. Each object in the array will have a Key (the EnterpriseGuid) and Value (the name of the enterprise).
[{"Key":"960c26b7-af6b-4eea-93b8-30168891b30e","Value":"Sandbox of Example Customer"}]
Once you have selected an enterprise, you will need to obtain a list of sites the user has access to. This is done using the GetSSOSites method.
GET https://services.etosoftware.ca/API/Security.svc/GetSSOSites/<authToken>/<enterpriseGuid> Content-Type: application/json Accept: application/json
A JSON array of site objects. Each object has a Key (the SiteID) and a Value (the name of the site).
[{"Key":76,"Value":"Example Intake Site"}]
With the SiteID, EnterpriseGuid, and AuthToken, you can now select the site context for the user.
GET https://services.etosoftware.ca/API/Security.svc/SSOSiteLogin/<siteId>/<enterpriseGuid>/<authToken>/<timezoneOffset>
The response will be a security token for the session. This security token will be used for all data operations once authentication is complete.
"f6157a62-bdd6-49a5-b3d2-fb8f9cf7a241"
Once you have successfully selected a site, you can obtain a list of programs available in the site for the current session. This API method requires both an EnterpriseGuid and Security Token to be passed as headers to the request.
GET https://services.etosoftware.ca/API/Form.svc/Forms/Program/GetPrograms/<siteId> Content-Type: application/json enterpriseGuid: <enterpriseGuid> securityToken: <securityToken>
The response to this request is an array of JSON objects representing the collection of programs available to the session. The program object includes several important properties including:
[{"AcceptEnterprise":false,"AcceptSite":false,"AcceptsReferrals":false,"Address1":null,
"Address2":null,"Administrative":false,"AuditDate":"\/Date(-62135578800000-0500)\/",
"AuditStaffID":0,"AutoAccept":false,"AutoDismiss":false,"AutoDismissAfterDays":null,
"AutoDismissAfterHours":null,"AutoDismissAfterTime":null,"AutoDismissReasonID":null,
"Billable":false,"Confidential":false,"Description":null,"Disabled":false,
"GUID":"00000000-0000-0000-0000-000000000000","ID":738,"Latitude":null,"Longitude":null,
"Name":"Example Program","PhoneNumber":null,"ZipCode":null},
{"AcceptEnterprise":false,"AcceptSite":false,"AcceptsReferrals":false,"Address1":null,
"Address2":null,"Administrative":false,"AuditDate":"\/Date(-62135578800000-0500)\/",
"AuditStaffID":0,"AutoAccept":false,"AutoDismiss":false,"AutoDismissAfterDays":null,
"AutoDismissAfterHours":null,"AutoDismissAfterTime":null,"AutoDismissReasonID":null,
"Billable":false,"Confidential":false,"Description":null,"Disabled":false,
"GUID":"00000000-0000-0000-0000-000000000000","ID":734,"Latitude":null,"Longitude":null,
"Name":"Second Example Program","PhoneNumber":null,"ZipCode":null}]
Most data operations in ETO Software are performed in the context of a program. This method allows you to set the session’s current program. This method is called via HTTP POST with the body of the request specifying the ProgramID in JSON.
POST /API/Security.svc/UpdateCurrentProgram/
Content-Type: application/json
Accept: application/json
enterpriseGuid: <enterpriseGuid>
securityToken: <securityToken>
{"ProgramID":<programId>}
The response to this API call is an UpdateCurrentProgramResult in JSON that contains the session’s detail.
{"UpdateCurrentProgramResult":
{"CountryCode":"US","EnterpriseName":"etoSandbox_example","LoginID":100000,
"LoginName":"email@example.com","LoginType":"Staff","ProgramID":768,
"ProgramName":"Example Program","Role":"Site Manager","RoleID":3,
"SSOAuthToken":"39a0d90d-35b0-419c-8873-ecabc085c74d",
"SecurityToken":"0a16a6be-e420-415d-ae3d-db32d70f1e1f",
"SiteID":76,"SiteName":"Example Site","SiteTimeZone":"","StaffID":1000,
"StaffName":"Example Account","UTCOffset":5,"UserName":null}
}
Once your session is authenticated and authorized against a specific site and program, you can perform data operations with participants and other subjects in ETO Software.