API Operations for Organizations

Summary

Operation Name: Retrieve an Organization by Organization ID
Relative API Request Path: ~/api/v1/organizations/{organizationID}
HTTP Verb: GET
Description: Retrieve a single Organization by Organization ID.

Operation Name: Retrieve all Organizations
Relative API Request Path: ~/api/v1/organizations
HTTP Verb: GET
Description: Retrieve a collection of currently defined Organizations.

Operation Name: Create an Organization
Relative API Request Path: ~/api/v1/organizations
HTTP Verb: POST
Description: Creates a new Organization associated with a specific OrganizationID.

Operation Name: Update an Organization
Relative API Request Path: ~/api/v1/organizations
HTTP Verb: PUT
Description: Updates an existing Organization associated with a specific OrganizationID.

 

Retrieve an Organization by Organization ID

This API method retrieves an Organization from the Issuetrak data store for a specified Organization ID. The organizationID parameter must correspond to an existing Organization. If there is no such Organization ID, an error message will be returned with an HTTP response status code of 404.

When retrieving an Organization using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. Therefore, please note that the OrganizationName returned via the API method represents the OrganizationName as stored within the Issuetrak database. Thus, when retrieving an Organization created through the Issuetrak web interface where HTML encoding of the OrganizationName is performed, the API consumer may desire to perform additional client-side decoding.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized ReadOrganizationDTO instance.

Response DTO Schema: 
ReadOrganizationDTO
 {
ExtensionData (Array[CustomKeyValuePairDataElement]),
Metadata (Array[CustomKeyValuePairDataElement]),
OrganizationID (integer),
CreatedBy (string),
CreatedDate (string): ISO 8601 string,
ModifiedBy (string),
ModifiedDate (string): ISO 8601 string,
IssueTrakUser (string),
OrganizationName (string),
Address1 (string),
Address2 (string),
City (string),
State (string),
Zip (string),
Phone (string),
WebAddress (string),
IsInternalOnly (boolean),
UserDefined1 (string),
UserDefined2 (string),
UserDefined3 (string),
UserDefined4 (string),
UserDefined5 (string),
UserDefinedID1 (integer),
UserDefinedID2 (integer),
UserDefinedID3 (integer),
UserDefinedID4 (integer),
UserDefinedID5 (integer),
UserDefinedDate1 (string): ISO 8601 string,
UserDefinedDate2 (string): ISO 8601 string,
Note (string),
ContactPerson (string),
Email (string),
BillingReference (string),
TitleLogoLeftLink (string),
TitleLogoRightLink (string),
SiteTitle (string),
EmailFromName (string),
EmailFromAddress (string)
}
CustomKeyValuePairDataElement 
{
Key (string, optional),
Value (object, optional)
}

Request HTTP Verb: GET

Response Status Codes:

  • Success: 200
  • Invalid Organization ID: 400 (Bad Request, e.g., a negative integer is supplied)
  • Non-existent Organization: 404
  • Invalid Organization ID: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)
Response DTO Property Notes:
  • The ExtensionData property is not used in version 1 of the API.
  • The Metadata property provides a key/value collection of additional data about the API operation and/or the response body.
  • BREAKING CHANGES from Previous API Versions:
    • The “AutoAssignTo” (string) property has been removed as of Issuetrak API 10.0.

Sample Request URL: ~/api/v1/organizations/11

Sample Response: 
{
  "ExtensionData": [
    {
      "Key": "string",
      "Value": {}
    }
  ],
  "Metadata": [
    {
      "Key": "string",
      "Value": {}
    }
  ],
  "OrganizationID": 0,
  "CreatedBy": "string",
  "CreatedDate": "string",
  "ModifiedBy": "string",
  "ModifiedDate": "string",
  "IssueTrakUser": "string",
  "OrganizationName": "string",
  "Address1": "string",
  "Address2": "string",
  "City": "string",
  "State": "string",
  "Zip": "string",
  "Phone": "string",
  "WebAddress": "string",
  "IsInternalOnly": true,
  "UserDefined1": "string",
  "UserDefined2": "string",
  "UserDefined3": "string",
  "UserDefined4": "string",
  "UserDefined5": "string",
  "UserDefinedID1": 0,
  "UserDefinedID2": 0,
  "UserDefinedID3": 0,
  "UserDefinedID4": 0,
  "UserDefinedID5": 0,
  "UserDefinedDate1": "string",
  "UserDefinedDate2": "string",
  "Note": "string",
  "ContactPerson": "string",
  "Email": "string",
  "BillingReference": "string",
  "TitleLogoLeftLink": "string",
  "TitleLogoRightLink": "string",
  "SiteTitle": "string",
  "EmailFromName": "string",
  "EmailFromAddress": "string"
}
 

Retrieve all Organizations

This API method retrieves a collection of all currently-defined Organizations from the Issuetrak data store.

When retrieving an Organization using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. Therefore, please note that the OrganizationName returned via the API method represents the OrganizationName as stored within the Issuetrak database. Thus, when retrieving an Organization created through the Issuetrak web interface where HTML encoding of the OrganizationName is performed, the API consumer may desire to perform additional client-side decoding.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized collection of ReadOrganizationDTO instance.

Response DTO Schema: 
 QueryResultsContainer[ReadOrganizationDTO] {
IsPageIndexZeroBased (boolean, optional),
PageIndex (integer, optional),
CountForPage (integer, optional),
PageSize (integer, optional),
TotalCount (integer, optional),
Collection (Array[ReadOrganizationDTO], optional)
}ReadOrganizationDTO {
ExtensionData (Array[CustomKeyValuePairDataElement]),
Metadata (Array[CustomKeyValuePairDataElement]),
OrganizationID (integer),
CreatedBy (string),
CreatedDate (string): ISO 8601 string,
ModifiedBy (string),
ModifiedDate (string): ISO 8601 string,
IssueTrakUser (string),
OrganizationName (string),
Address1 (string),
Address2 (string),
City (string),
State (string),
Zip (string),
Phone (string),
WebAddress (string),
IsInternalOnly (boolean),
UserDefined1 (string),
UserDefined2 (string),
UserDefined3 (string),
UserDefined4 (string),
UserDefined5 (string),
UserDefinedID1 (integer),
UserDefinedID2 (integer),
UserDefinedID3 (integer),
UserDefinedID4 (integer),
UserDefinedID5 (integer),
UserDefinedDate1 (string): ISO 8601 string,
UserDefinedDate2 (string): ISO 8601 string,
Note (string),
ContactPerson (string),
Email (string),
BillingReference (string),
TitleLogoLeftLink (string),
TitleLogoRightLink (string),
SiteTitle (string),
EmailFromName (string),
EmailFromAddress (string)
}CustomKeyValuePairDataElement {
Key (string, optional),
Value (object, optional)
}

Request HTTP Verb: GET

Response Status Codes:

  • Success: 200
  • Non-existent Organization: 404
Response DTO Property Notes:
  • The IsPageIndexZeroBased property value is always true. This property is included for use in future API versions.
  • The PageIndex property value is always 0. This property is included for use in future API versions.
  • The CountForPage property value is always the same as TotalCount. This property is included for use in future API versions.
  • The PageSize property value is always the maximum value for a signed, 32-bit integer. This property is included for use in future API versions.
  • The TotalCount property value is the number of records returned in the collection.
  • The Collection property is an array containing the ReadOrganizationDTO objects returned.
  • The ExtensionData property is not implemented in v1 of the API.
  • BREAKING CHANGES from Previous API Versions:
    • The “AutoAssignTo” (string) property has been removed as of Issuetrak API 10.0.

Sample Request URL: ~/api/v1/organizations/

Sample Response: 
{
  "IsPageIndexZeroBased": true,
  "PageIndex": 0,
  "CountForPage": 0,
  "PageSize": 0,
  "TotalCount": 0,
  "Collection": [
    {
      "ExtensionData": [
        {
          "Key": "string",
          "Value": {}
        }
      ],
      "Metadata": [
        {
          "Key": "string",
          "Value": {}
        }
      ],
      "OrganizationID": 0,
      "CreatedBy": "string",
      "CreatedDate": "string",
      "ModifiedBy": "string",
      "ModifiedDate": "string",
      "IssueTrakUser": "string",
      "OrganizationName": "string",
      "Address1": "string",
      "Address2": "string",
      "City": "string",
      "State": "string",
      "Zip": "string",
      "Phone": "string",
      "WebAddress": "string",
      "IsInternalOnly": true,
      "UserDefined1": "string",
      "UserDefined2": "string",
      "UserDefined3": "string",
      "UserDefined4": "string",
      "UserDefined5": "string",
      "UserDefinedID1": 0,
      "UserDefinedID2": 0,
      "UserDefinedID3": 0,
      "UserDefinedID4": 0,
      "UserDefinedID5": 0,
      "UserDefinedDate1": "string",
      "UserDefinedDate2": "string",
      "Note": "string",
      "ContactPerson": "string",
      "Email": "string",
      "BillingReference": "string",
      "TitleLogoLeftLink": "string",
      "TitleLogoRightLink": "string",
      "SiteTitle": "string",
      "EmailFromName": "string",
      "EmailFromAddress": "string"
    }
  ]
}
 

Create an Organization

This API method creates a new Organization associated with a specific OrganizationID within the Issuetrak data store. The CreateOrganizationModel object conveys the properties of the new Organization.

The response code on success will be 201 (Created), and the response body will represent the text value representing the ID of the newly-created Organization.

When creating a Organization using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed.

All string properties have a maximum length of 50 unless specified otherwise.

Response DTO Schema: 
CreateOrganizationModel {
 OrganizationName (string),
 Address1 (string),
 Address2 (string),
 City (string),
 State (string),
 Zip (string),
 Phone (string),
 WebAddress (string),
 IsInternalOnly (boolean),
 UserDefined1 (string),
 UserDefined2 (string),
 UserDefined3 (string),
 UserDefined4 (string),
 UserDefined5 (string),
 UserDefinedID1 (integer),
 UserDefinedID2 (integer),
 UserDefinedID3 (integer),
 UserDefinedID4 (integer),
 UserDefinedID5 (integer),
 UserDefinedDate1 (string): ISO 8601 string ,
 UserDefinedDate2 (string): ISO 8601 string ,
 Note (string),
 ContactPerson (string),
 Email (string),
 BillingReference (string),
 TitleLogoLeftLink (string),
 TitleLogoRightLink (string),
 SiteTitle (string),
 EmailFromName (string),
 EmailFromAddress (string)
}

Request HTTP Verb: POST

Response Status Codes:

  • Success: 201
  • Invalid Data: 400 (Bad Request, e.g., a negative integer is supplied)
  • Invalid Organization DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)
Response DTO Property Notes:
Property Name Required Max length
OrganizationID ✔ 50
IssueTrakUser If used, must point to an Active user with an Organization. 50
OrganizationName ✔ 50
Address1 ✖ 50
Address2 ✖ 50
City ✖ 50
State ✖ 20
Zip ✖ 20
Phone ✖ 50
WebAddress ✖ 1000
IsInternalOnly ✖ 50
UserDefined1 ✖ 200
UserDefined2 ✖ 200
UserDefined3 ✖ 200
UserDefined4 ✖ 200
UserDefined5 ✖ 200
UserDefinedID1 If used, must reference an existing UserDefinedList1 within the Issuetrak application. 50
UserDefinedID2 If used, must reference an existing UserDefinedList2 within the Issuetrak application. 50
UserDefinedID3 If used, must reference an existing UserDefinedList3 within the Issuetrak application. 50
UserDefinedID4 If used, must reference an existing UserDefinedList4 within the Issuetrak application. 50
UserDefinedID5 If used, must reference an existing UserDefinedList5 within the Issuetrak application. 50
UserDefinedDate1 ✖ 50
UserDefinedDate2 ✖ 50
Note ✖ 1000
ContactPerson ✖ 50
Email Must be a valid email if set. 50
BillingReferrence ✖ 50
TitleLogoLeftLink Must be a valid url if set. 500
TitleLogoRightLink Must be a valid url if set. 500
SiteTitle ✖ 500
EmailFromName ✖ 50
EmailFromAddress Only required if EmailFromName is specified 50

Sample Request URL: ~/api/v1/organizations

 

Update an Organization

This API method updates an existing Organization associated with a specific OrganizationID within the Issuetrak data store. The UpdateOrganizationModel object conveys the properties of the Organization. If invalid data are supplied, an error message will be returned with a 400 HTTP status code.

The response code on success will be 200 (OK), and the response body will represent the text value representing the ID of the Organization.

When updating a Organization using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed.

All string properties have a max length of 50 unless specified otherwise

Response DTO Schema: 
UpdateOrganizationModel {
 OrganizationID (integer),
 IssueTrakUser (string),
 OrganizationName (string),
 Address1 (string),
 Address2 (string),
 City (string),
 State (string),
 Zip (string),
 Phone (string),
 WebAddress (string),
 IsInternalOnly (boolean),
 UserDefined1 (string),
 UserDefined2 (string),
 UserDefined3 (string),
 UserDefined4 (string),
 UserDefined5 (string),
 UserDefinedID1 (integer),
 UserDefinedID2 (integer),
 UserDefinedID3 (integer),
 UserDefinedID4 (integer),
 UserDefinedID5 (integer),
 UserDefinedDate1 (string): ISO 8601 string ,
 UserDefinedDate2 (string): ISO 8601 string ,
 Note (string),
 ContactPerson (string),
 Email (string),
 BillingReference (string),
 TitleLogoLeftLink (string),
 TitleLogoRightLink (string),
 SiteTitle (string),
 EmailFromName (string),
 EmailFromAddress (string)
}

Request HTTP Verb: PUT

Response Status Codes:

  • Success: 200
  • Invalid Data: 400 (Bad Request, e.g., a negative integer is supplied)
  • Invalid Organization DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)
Response DTO Property Notes:
Property Name Required Max length
OrganizationID ✔ 50
IssueTrakUser If used, must point to an Active user with an Organization. 50
OrganizationName ✔ 50
Address1 ✖ 50
Address2 ✖ 50
City ✖ 50
State ✖ 20
Zip ✖ 20
Phone ✖ 50
WebAddress ✖ 1000
IsInternalOnly ✖ 50
UserDefined1 ✖ 200
UserDefined2 ✖ 200
UserDefined3 ✖ 200
UserDefined4 ✖ 200
UserDefined5 ✖ 200
UserDefinedID1 If used, must reference an existing UserDefinedList1 within the Issuetrak application. 50
UserDefinedID2 If used, must reference an existing UserDefinedList2 within the Issuetrak application. 50
UserDefinedID3 If used, must reference an existing UserDefinedList3 within the Issuetrak application. 50
UserDefinedID4 If used, must reference an existing UserDefinedList4 within the Issuetrak application. 50
UserDefinedID5 If used, must reference an existing UserDefinedList5 within the Issuetrak application. 50
UserDefinedDate1 ✖ 50
UserDefinedDate2 ✖ 50
Note ✖ 1000
ContactPerson ✖ 50
Email Must be a valid email if set. 50
BillingReferrence ✖ 50
TitleLogoLeftLink Must be a valid url if set. 500
TitleLogoRightLink Must be a valid url if set. 500
SiteTitle ✖ 500
EmailFromName ✖ 50
EmailFromAddress Only required if EmailFromName is specified 50

Sample Request URL: ~/api/v1/organizations

Was this article helpful?
Thank you for your feedback!
User Icon

Thank you! Your comment has been submitted for approval.

Related Articles

 Copyright © Issuetrak, Inc. All rights reserved.