{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"705e6f98-a80d-4281-b7bd-bf4cbe1ed48d","name":"CrewSourcing API","description":"![image](https://i.imgur.com/X2C1kdJ.jpg)\n\nWelcome to UtilityGO! CrewSourcing API. Here are some pre-made requests for you to explore the API using [Postman](https://getpostman.com).\n\n## Getting Started\n\nUtilityGO! CrewSourcing API exposes the entire web/mobile client infrastructure via a standardized programmatic interface. Using UtilityGO! CrewSourcing API, you can do just about anything you can do on both the web and mobile applications, while using your programming language of choice. The UtilityGO! CrewSourcing API is a RESTful API based on HTTP requests and JSON responses.\n\nThe easiest way to start using the UtilityGO! CrewSourcing API is by clicking the **Run in Postman** button above. [Postman](https://www.getpostman.com/) is a free tool which helps developers run and debug API requests, and is the source of truth for this documentation. Every endpoint you see documented here is readily available by running our Postman collection.\n\n# Setup\n\nYou'll need to [create an environment in Postman](https://www.getpostman.com/docs/environments), select that environment, and enter your target **Utility-ID** in the `Setup/Environment Setup` pre-request script ([documentation on pre-request scripts](http://www.getpostman.com/docs/pre_request_scripts)) to set the required environment variables.\n\n## Environments & Utilities\n\n|Environment | Base API Url                                  |\n------------ | ----------------------------------------------|\n|Development | https://crewsourcing-api-dev.widergydev.com   |\n|QA          | https://crewsourcing-api-qa.widergydev.com    |\n|Stage       | https://crewsourcing-api-stage.widergydev.com |\n|Production  | https://crewsourcing-api.widergy.com          |\n\n|Utility | ID|\n|------- | --|\n|Camuzzi | 1 |\n\nNotes:\n- Data created or modified in each environment will not affect the other.\n- Data created or modified in each Utility will not affect the other.\n- Data cannot be transfered from one environment/Utility to the other.\n\n## Making Your First Call\n\nMaking your first call test that you have the environment variables setup by making a `GET` request to `/health_check/all` with the `Utility-ID` header set to your target utility. You should get a `HTTP 200 OK` response if your variables are correct and the API is healthy :)\n\n# Authentication\n\nThe API uses [JWT](https://jwt.io/introduction/) token based authentication for both _User_ & _Consumer_ (consider _clients_) models.\n\n## Sessions\n\nWhen you [create a session](), it generates an `access_token` and `renew_id` for a given _client_ credentials.\n\nAn `access_token` is unique to a given _client_ and device. This `access_token` is used in every authenticated endpoint by passing the `Authorization` header to the request. The `renew_id` is unique per _client_ and device, and is unique for the `access_token`. The `renew_id` will be used in the [renew_token endpoint](). The `renew_id` changes only when the _client_ is unauthorized and requests a new `access_token` again.\n\n### Renewing A Session\n\nIf a _client_ has authorized their account but you no longer have a valid `access_token` for them, then a new one can be generated by using the `renew_id`.\n\nWhen your application receives a `renew_id`, it is important to store it for future use. If your application loses the `renew_id`, you will have to prompt the _client_ for their login information again.\n\nWhen a response from server returns the custom http header `X-Expiration-Warning` it means the expiration date of the token is near and it's recommended to get a new `access_token` with a renew call. If the token is not renewed in a certain time, then the `access_token` will not longer be valid and the _client_ must generate a new one. Despite the [renew_token endpoint](), the server always unauthorizes a _client_ after certain time.\n    \n# Making your requests\n\nCongrats! You must have the client's `access_token` at this point and you're ready to start making API requests to their behalf. All that's required for this is to set the required headers in your requests:\n\n    Utility-ID:    <YOUR-TARGET-UTILITY-ID>\n    Authorization: <YOUR-ACCESS-TOKEN>\n    \n## Public resoruces\n\nFor public read-only and anonymous resources, such as creating a user, requesting a user's password reset, etc. all you need to do is send the `Utility-ID` header with your target utility in your requests.\n\n    Utility-ID: <YOUR-TARGET-UTILITY-ID>\n\n## Endpoints\n\nThe API is accessed by making HTTP requests to a specific version endpoint URL, in which GET, POST, PUT, PATCH, DELETE calls contain information about what you wish to access. Every endpoint is accessed via SSL-enabled HTTPS.\n\n### Pagination\n\nIn several cases, if the API action is plural, you can page it via query string parameters.\n\nNOTE: check each endpoint specification to know if it allows pagination.\n\n| Query String Parameter | Required | Description                                                  |\n|------------------------|----------|--------------------------------------------------------------|\n| page                   | optional | Page number of the result set (default: 1)                   |\n| page_size              | optional | Limit the number of results per page. (default: 20, max: n/a)|\n\nExample:\n\n    https://utilitygo-crewsourcing-api-dev.widergydev.com/api/v1/accounts?page=2&page_size=30\n\n## Responses\n\nResponses are always in JSON. There's no support for other formats like XML.\n\nHere are the [HTTP Status Codes](https://httpstatuses.com/) mostly used by this API. \n\n`200 OK`: The request has succeeded.\n\n`201 Created`: The request has been fulfilled and has resulted in one or more new resources being created.\n\n`202 Accepted`: The request has been accepted for processing, but the processing has not been completed.\n\n`204 No Content`: The server has successfully fulfilled the request and that there is no additional content to send in the response payload body.\n\n`400 Bad Request`: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, etc.).\n\n`401 Unauthorized`: The request has been refused because it lacks valid authentication credentials for the target resource.\n\n`403 Forbidden`: The server understood the request but refuses to authorize it.\n\n`404 Not Found`: The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.\n\n`422 Unprocessable Entity`: The server understood the request but was unable to process the contained instructions.\n\n`500 Internal Server Error`: The server encountered an unexpected condition that prevented it from fulfilling the request.\n\n`501 Not Implemented`: The server does not support the functionality required to fulfill the request.\n\n`504 Gateway Timeout`: The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.\n\n## Errors\n\nDepending the case, the API will stop processing a request as soon as a problem is encountered, or in some cases it will continue processing and encounter multiple problems. For instance, it might process multiple attributes and then return multiple validation problems in a single response.\n\nWhen the API encounters multiple problems for a single request, the most generally applicable HTTP error will be used in the response. For instance, `400 Bad Request` might be appropriate for multiple 4xx errors or `500 Internal Server Error` might be appropriate for multiple 5xx errors.\n\n### Error Objects\n\nError objects provide additional information about problems encountered while performing an operation. Error objects will be returned as an array keyed by `errors` in the top level of the response body.\n\nAn error object will have the following members:\n\n```json\n{\n\t\"errors\": [\n\t\t{\n\t\t\t\"status\": 400,\n\t\t\t\"code\": \"param_is_missing\",\n\t\t\t\"message\": \"Algo salió mal. Por favor intente nuevamente más tarde.\",\n\t\t\t\"meta\": \"param is missing or the value is empty: \\\"email\\\"\"\n\t\t}\n\t]\t\n}\n```\n\n\n- `status`: the HTTP status code applicable to this problem, expressed as a integer value.\n- `code`: an application-specific error code, expressed as a string value.\n- `message`: a human-readable explanation specific to this occurrence of the problem.\n- `meta`: non-standard meta-information about the error.\n\nWe've developed a JavaScript based [utils library](https://github.com/widergy/web-utils) which has a built-in function to handle these kind of error responses. Check it out!\n\n# Polling\n\nFor the most part, one common issue we face at the time of interacting with the API is making requests that depend on the utilities external service’s response. Let’s say we have to log a user into our application and the login process goes as follows:\n\n![image](https://cdn-images-1.medium.com/max/1600/1*qmatI22gPiI87bFtdSSV0w.gif)\n\nAlthough this is a valid way of logging in a user, it has several drawbacks:\n\n- Response time now depends on an external resource we do not control.\n- If the external server is slow, our server might suffer from a DOS (Denial of Service) without even having a malicious client trying to force it.\n- Our entire application will seem to be slow because threads will be consuming most of their time in this slow request.\n\nWe decided to tackle this issue with the following architecture:\n\n![image](https://cdn-images-1.medium.com/max/1600/1*B1L_xA13Rnlqn1xGPhorMA.gif)\n\n**1.** The client makes a request to our server.\n\n**2.** The server queues a task to process the requested action and returns a job_id to the client.\n\n**3.** While the task is being processed, our endpoint returns 202 (Accepted) each time the client requests the job’s status.\n\n**4.** Once the job is processed, the server responds with the job result.\n\nWith this approach, our server’s response time doesn’t depend on external resources we do not control. Hence, we don’t have the drawbacks presented in the previous section. On the other hand, this requires the client to implement a busy-waiting loop, adding complexity to their code.\n\nLuckily, for JavaScript based interactions, at Widergy we've develop the [polling-handling library](https://github.com/widergy/polling-handling) which let you start consuming these endpoints much faster 🚀. Check it out!\n\nNOTE: check each endpoint specification to know if it implements polling or not.\n\n## Questions / Comments / Suggestions\n\nIf you have any questions or comments, please let us know at [widergydev@widergy.com](mailto:widergydev@widergy.com).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"3397322","collectionId":"705e6f98-a80d-4281-b7bd-bf4cbe1ed48d","publishedId":"S1LvV8AU","public":true,"publicUrl":"https://crewsourcing-api-docs.widergydev.com","privateUrl":"https://go.postman.co/documentation/3397322-705e6f98-a80d-4281-b7bd-bf4cbe1ed48d","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"07DB7C"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"07DB7C"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"07DB7C"}}]}},"version":"8.10.0","publishDate":"2025-03-28T13:05:33.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/7ac48006028d2d936c8133fcb86cc30ac2d607cd67f07ee0e75503dcc1bc49a0","favicon":"https://res.cloudinary.com/postman/image/upload/v1639162729/team/qbas86ci5xiwrn4uvuuj.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://crewsourcing-api-docs.widergydev.com/view/metadata/S1LvV8AU"}