Skip to content

Latest commit

 

History

History
285 lines (254 loc) · 7.91 KB

01.creating_a_signal.md

File metadata and controls

285 lines (254 loc) · 7.91 KB

Private V1 Signals

Creating a Signal

To create a Signal a POST call can be executed to the private V1 signals endpoint.

The endpoint used for creating a Signal is /signals/v1/private/signals and it requires a valid bearer token in the authorization header.

A Signal always contains the following information:

What Explanation
text The "complaint"
location The coordinates are the bare minimum that can be provided
category The url/path of the category a Signal belongs to. To determine the category machine learning is used
Reporter This field is required, however the email address and telephone number can be left empty if a citizen wants to be anonymous
incident_date_start When was the "complaint", this can be in the past
source How did we receive the complaint? The source must exists in the database

A minimal example:

URL: http://127.0.0.1:8000/signals/v1/private/signals

Request headers:

  • Authorization: Bearer {TOKEN}
  • Content-Type: application/json

Request body:

{
    "text": "My complaint",
    "location": {
        "geometrie": {
            "type": "Point",
            "coordinates": [
                4.90022563,
                52.36768424
            ]
        }
    },
    "category": {
        "sub_category": "/signals/v1/public/terms/categories/overig/sub_categories/overig"
    },
    "reporter": {
        "email": "[email protected]",
        "sharing_allowed": true
    },
    "incident_date_start": "2022-11-24T12:00:00+01:00",
    "source": "Telefoon – Adoptant"
}

Response body:

{
    "_links": {
        "self": {
            "href": "http://127.0.0.1:8000/signals/v1/private/signals/1"
        }
    },
    "_display": "1 - m - None - 2022-11-24T12:00:00+01:00",
    "id": 1,
    "id_display": "SIG-1",
    "signal_id": "cfa97730-902a-44fe-bd98-21ac2675b938",
    "source": "Telefoon – Adoptant",
    "text": "My complaint",
    "text_extra": "",
    "status": {
        "text": null,
        "user": "[email protected]",
        "state": "m",
        "state_display": "Gemeld",
        "target_api": null,
        "extra_properties": null,
        "send_email": false,
        "created_at": "2022-11-24T12:00:00+01:00"
    },
    "location": {
        "id": 1,
        "stadsdeel": "A",
        "buurt_code": null,
        "area_type_code": null,
        "area_code": null,
        "area_name": null,
        "address": null,
        "address_text": "",
        "geometrie": {
            "type": "Point",
            "coordinates": [
                4.90022563,
                52.36768424
            ]
        },
        "extra_properties": null,
        "created_by": "[email protected]",
        "bag_validated": false
    },
    "category": {
        "sub": "Overig",
        "sub_slug": "overig",
        "main": "Overig",
        "main_slug": "overig",
        "category_url": "http://127.0.0.1:8000/signals/v1/public/terms/categories/overig/sub_categories/overig",
        "departments": "ASC",
        "created_by": "[email protected]",
        "text": null,
        "deadline": "2022-12-01T12:00:00+01:00",
        "deadline_factor_3": "2022-12-15T12:00:00+01:00"
    },
    "reporter": {
        "email": "[email protected]",
        "phone": "",
        "sharing_allowed": true,
        "allows_contact": true
    },
    "priority": {
        "priority": "normal",
        "created_by": "[email protected]"
    },
    "type": {
        "code": "SIG",
        "created_at": "2022-11-24T12:00:00+01:00",
        "created_by": "[email protected]"
    },
    "created_at": "2022-11-24T12:00:00+01:00",
    "updated_at": "2022-11-24T12:00:00+01:00",
    "incident_date_start": "2022-11-24T12:00:00+01:00",
    "incident_date_end": null,
    "operational_date": null,
    "has_attachments": false,
    "extra_properties": null,
    "notes": [
        {
            "text": "Automatische e-mail bij registratie van de melding is verzonden aan de melder.",
            "created_by": null
        }
    ],
    "has_parent": false,
    "has_children": false,
    "assigned_user_email": null
}

cURL:

curl --location --request POST 'http://127.0.0.1:8000/signals/v1/private/signals/' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "text": "My complaint",
    "location": {
        "geometrie": {
            "type": "Point",
            "coordinates": [
                4.90022563,
                52.36768424
            ]
        }
    },
    "category": {
        "sub_category": "/signals/v1/public/terms/categories/overig/sub_categories/overig"
    },
    "reporter": {
        "email": "[email protected]",
        "sharing_allowed": true
    },
    "incident_date_start": "2022-11-24T12:00:00+01:00",
    "source": "Telefoon – Adoptant"
}
'

How to add more details when creating a Signal?

In the previous example we saw the bare minimum that is required to create a Signal. It is possible to add more details when creating a Signal.

Location

Location is required when creating a Signal, as we can see in the example above. However, the bare minimum that is required are the coordinates. It is possible to add even more information about the address.

Example:

{
    "location": {
        "geometrie": {
            "type": "Point",
            "coordinates": [
                4.90022563,
                52.36768424
            ]
        },
        "address": {
            "openbare_ruimte": "Amstel",
            "huisnummer": 1,
            "huisletter": "",
            "huisnummer_toevoeging": "",
            "postcode": "1011PN",
            "woonplaats": "Amsterdam"
        }
    }
}

Priority

The default priority of Signal is normal (Signal/Melding). There are several other priorities that can be used.

Priority EN NL
low low laag
normal normal normaal
high high hoog

Example:

{
  "priority": {
    "priority": "low"
  }
}

Type

The default type of Signal is SIG (Signal/Melding). There are several other types that can be used.

Type EN NL
SIG Signal Melding
REQ Request Aanvraag
QUE Question Vraag
COM Complaint Klacht
MAI Maintenance Groot onderhoud

Example:

{
  "type": {
    "code": "REQ"
  }
}

Adding attachments

When a Signal has been created attachments can be added.

Example

URL: http://127.0.0.1:8000/signals/v1/private/signals/1/attachments/

Request headers:

  • Authorization: Bearer {TOKEN}
  • Content-Type: application/json

cURL:

curl 'http://127.0.0.1:8000/signals/v1/private/signals/1/attachments' \
  -X 'POST' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: */*' \
  -F 'file=@/path/to/image/image-123.jpg;type=image/jpeg'

Response:

{
  "_display": "Attachment object (1)",
  "_links": {
    "self": {
      "href": "http://127.0.0.1:8000/signals/v1/private/signals/1/attachments/1"
    }
  },
  "location": "http://127.0.0.1:8000/signals/media/attachments/2022/11/24/image-123.jpg",
  "is_image": true,
  "created_at": "2022-11-24T12:00:00+01:00",
  "created_by": "[email protected]"
}