Authentication

Example - Headers

Accept: application/json
Authorization: API_KEY

USD will provide you with your personal API key.

You must include this API key in the Authorization header of each request.

Plus, the Accept header must be set to application/json.

For the testing environment, use the following URL: https://usd-staging.demo.ixmedia.com/api/v1/

For the production environment, use the following URL: https://www.reparemonbac.ca/api/v1/

Citizen request

Create citizen request

This endpoint allows you to create citizen requests.

Example - Request

POST https://www.reparemonbac.ca/api/v1/citizen_requests?locale=en

HTTP Request

POST https://www.reparemonbac.ca/api/v1/citizen_requests

Query string parameters

Example - JSON body

{
  "locale": "en",
  "appellation_id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "follow_up_preference": "email",
  "email": "example@domain.com",
  "address": {
    "address": "123 Test St",
    "city": "Quebec",
    "province": "QC",
    "postal_code": "H0H 0H0"
  },
  "bin_position": "46.750216117383566,-71.23968459351832",
  "bin_position_notes": "This is a note.",
  "bin_serial_number": "12345",
  "contractual_sector_id": 3,
  "bin_volume_id": 1,
  "bin_type_id": 1,
  "service_type_id": 1,
  "status_id": 3,
  "bin_part_ids": [1, 2, 3],
  "client_internal_number": "12345"
}

JSON body parameters

Response

Example - Success response

{
  "citizen_request": {
    "id": 4299,
    "citizen_request_number": "202211302024044299",
    "current_status": {
      "id": 5,
      "name": "Completed"
    }
  }
}

Example - Error response

{
  "errors": {
    "first_name": ["This field is required."],
    "last_name": ["This field is required."]
  }
}

If the request is created, then its ID and status will be returned. Otherwise, validation errors grouped by field will be returned.

In the case of a request with a duplicate client_internal_number, the id associated with the original request will be returned alongside the error message.

Update citizen request

This endpoint allows you to update a citizen requests, as long as it is still waiting to be approved or waiting transmission to USD (status 1 and 3 respectively. Refer to the citizen request statuses section).

You can also cancel a request by setting the status_id field to Rejected by municipality (2).

Example - Request

PUT https://www.reparemonbac.ca/api/v1/citizen_requests/4299?locale=en

HTTP Request

PUT https://www.reparemonbac.ca/api/v1/citizen_requests/:id

URL parameters

Query string parameters

JSON body parameters

The same parameters as the one used for the creation are authorized. See above.
You can also set the status_id field to Rejected by municipality (2).

Response

Example - Success response

{
  "citizen_request": {
    "id": 4299,
    "citizen_request_number": "202211302024044299",
    "current_status": {
      "id": 5,
      "name": "Completed"
    }
  }
}

Example - Error response

{
  "errors": {
    "first_name": ["This field is required."],
    "last_name": ["This field is required."]
  }
}

If the request is updated, then its ID and status will be returned. Otherwise, validation errors grouped by field will be returned.

Cancel citizen request

This endpoint allows you to cancel a citizen requests, as long as it is still waiting to be approved or waiting transmission to USD (status 1 and 3 respectively. Refer to the citizen request statuses section)

Example - Request

DELETE https://www.reparemonbac.ca/api/v1/citizen_requests/4299?locale=en

HTTP Request

DELETE https://www.reparemonbac.ca/api/v1/citizen_requests/:id

URL parameters

Query string parameters

Response

Sends back a 200 status if successful. Otherwise will send a 422 Error code if the request cannot be canceled

Get citizen request status

Returns the current status of a given citizen request.

Example - Request

GET https://www.reparemonbac.ca/api/v1/citizen_requests/8/status?locale=en

HTTP Request

GET https://www.reparemonbac.ca/api/v1/citizen_requests/:id/status

URL parameters

Query string parameters

Response

Example - Success response

{
  "citizen_request_status": {
    "id": 5,
    "name": "Completed"
  }
}

Example - Error response

{
  "message": "Request not found."
}

The current status is returned. To know the possible statuses, refer to the citizen request statuses section.

Get citizen request detail

Returns the current request of a given citizen request.

Example - Request

GET https://www.reparemonbac.ca/api/v1/citizen_requests/8?locale=en

HTTP Request

GET https://www.reparemonbac.ca/api/v1/citizen_requests/:id

URL parameters

Query string parameters

Response

Example - Success response

{
  "citizen_request": {
    "id": 1,
    "client_internal_number": "Test-1",
    "address": {
      "address": "123 Test St",
      "city": "Quebec",
      "province": "QC",
      "postal_code": "G6W 5M6"
    },
    "status": {
      "id": 5,
      "name": "Completed"
    },
    "intervention": {
      "intervention_type": "Replacement damaged bin (9000020004)",
      "pieces": "1X - Bac 360L charcoal Quebec (12345677X1XXX)",
      "notes": "Test note",
      "serial_number": "123-456789",
      "reason": null
    }
  }
}

Example - Error response

{
  "message": "Request not found."
}

The current request detail is returned with the request id, internal customer number, request status, full address and intervention details.

The details of the address contain:

• the civic number and the street name
• the city
• the province
• the postal code

The details of the intervention contain:

• the type of intervention
• the replaced parts
• the note added by USD
• the new serial number of the bin
• the reason why a request would have been canceled

To know the possible statuses, refer to the citizen request statuses section.

Citizen request statuses

The possible statuses are the following.

Contractual sector

Get contractual sectors

Returns the available contractual sectors based on your API key.

Example - Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors

HTTP Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors

Response

Example - Success response

{
  "contractual_sectors": [
    {
      "id": 3,
      "name": "My contractual sector"
    }
  ]
}

A list containing the available contractual sectors is returned. Each contractual sector has an ID and a name.

Get bin types

Returns the available bin types for a contractual sector.

Example - Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors/3/bin_types?locale=en

HTTP Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors/:id/bin_types

URL parameters

Query string parameters

Response

Example - Success response

{
  "bin_types": [
    {
      "id": 1,
      "name": "Recycling blue"
    },
    {
      "id": 5,
      "name": "Organics brown"
    }
  ]
}

A list containing the available bin types is returned. Each bin type has an ID and a name.

Get bin volumes

Returns the available bin volumes for a contractual sector.

Example - Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors/3/bin_volumes?locale=en

HTTP Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors/:id/bin_volumes

URL parameters

Query string parameters

Response

Example - Success response

{
  "bin_volumes": [
    {
      "id": 1,
      "name": "Mini bin"
    },
    {
      "id": 14,
      "name": "240L brown"
    }
  ]
}

A list containing the available bin volumes is returned. Each bin volume has an ID and a name.

Get service types

Returns the available service types for a contractual sector.

Example - Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors/3/service_types?locale=en

HTTP Request

GET https://www.reparemonbac.ca/api/v1/contractual_sectors/:id/service_types

URL parameters

Query string parameters

Response

Example - Success response

{
  "service_types": [
    {
      "id": 1,
      "name": "Repair service"
    },
    {
      "id": 2,
      "name": "Bin removal"
    }
  ]
}

A list containing the available service types is returned. Each service type has an ID and a name.

Errors

Example - 500 Internal Server Error

{
  "message": "An error has occurred."
}

Here are the error codes that can be returned by the API: