Editing API/Endpoints: Models

= Endpoints =

This page documents key Verofy API endpoints and usage patterns.

__TOC__

== Projects ==

=== Map Project (map-project) ===
A Map Project groups multiple mapping elements, such as segments, sites, and access points.

==== Fields ====
{| class="wikitable"
! Field !! Type !! Description
|-
| id || int || Unique identifier
|-
| name || string || Project name
|-
| description || string || Detailed project description
|-
| status || string || Project status (e.g., <code>active</code>, <code>completed</code>, <code>archived</code>)
|-
| created_at || datetime || Creation timestamp
|-
| updated_at || datetime || Last update timestamp
|}

==== Endpoints for Projects ====
; Read (VIEW)
<pre>GET {api_url}/{version}/map-project/{id}</pre>

; Create
<pre>POST {api_url}/{version}/map-project</pre>

; Update
<pre>PATCH {api_url}/{version}/map-project/{id}</pre>

; Upload Document
<pre>POST {api_url}/{version}/map-document/upload</pre>

; Download Document
<pre>GET {api_url}/{version}/map-document/download/{id}</pre>

=== Project Permissions ===
Permissions can be managed at the project level to restrict or allow access to users.

; Check user access to a project
<pre>GET {api_url}/{version}/map-project/permission/{mapProjectId}</pre>

; Bookmark a project for quick access
<pre>POST {api_url}/{version}/map-project/bookmark/{mapProjectId}</pre>

==== Miscellaneous Actions ====
Additional operations related to Map Projects that provide extended functionality.

===== Check User Permissions =====
Retrieve the access permissions for a specific project.

<pre>GET {api_url}/{version}/map-project/permission/{mapProjectId}</pre>

Example:
<pre>GET https://api.veronetworks.com/v1/map-project/permission/12345</pre>

===== Bookmark a Project =====
Mark a project for quick access.

<pre>POST {api_url}/{version}/map-project/bookmark/{mapProjectId}</pre>

Example:
<pre>POST https://api.veronetworks.com/v1/map-project/bookmark/12345</pre>

----

== Models ==

The Verofy API is RESTful. Most actions are addressed as:

<pre>&lt;api_url&gt;/&lt;version&gt;/&lt;model&gt;/&lt;id&gt;</pre>

Where:
* <code>&lt;api_url&gt;</code> is the base URL (e.g., <code>https://api.veronetworks.com</code>)
* <code>&lt;version&gt;</code> is the API version (e.g., <code>v1</code>)
* <code>&lt;model&gt;</code> is the object type (e.g., <code>map-segment</code>)
* <code>&lt;id&gt;</code> is the object id (when a specific record is required)

== Action Types ==
The following actions are supported:

; Read
<pre>Method: GET
Endpoint: {api_url}/{version}/{model}/{id}</pre>

; Create
<pre>Method: POST
Endpoint: {api_url}/{version}/{model}</pre>

; Update
<pre>Method: PATCH
Endpoint: {api_url}/{version}/{model}/{id}</pre>

----

== Modules and Endpoints ==

=== Map Access Point ===
; Read
<pre>GET {api_url}/{version}/map-access-points/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-access-points</pre>
; Create
<pre>POST {api_url}/{version}/map-access-points</pre>
; Update
<pre>PATCH {api_url}/{version}/map-access-points/{id}</pre>

=== Map Cable ===
; Read
<pre>GET {api_url}/{version}/map-cables/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-cables</pre>
; Create
<pre>POST {api_url}/{version}/map-cables</pre>
; Update
<pre>PATCH {api_url}/{version}/map-cables/{id}</pre>

=== Map Document ===
; Read
<pre>GET {api_url}/{version}/map-documents/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-documents</pre>
; Create
<pre>POST {api_url}/{version}/map-documents</pre>
; Update
<pre>PATCH {api_url}/{version}/map-documents/{id}</pre>

=== Map Element ===
; Read
<pre>GET {api_url}/{version}/map-elements/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-elements</pre>
; Create
<pre>POST {api_url}/{version}/map-elements</pre>
; Update
<pre>PATCH {api_url}/{version}/map-elements/{id}</pre>

=== Map Info Object ===
; Read
<pre>GET {api_url}/{version}/map-info-objects/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-info-objects</pre>
; Create
<pre>POST {api_url}/{version}/map-info-objects</pre>
; Update
<pre>PATCH {api_url}/{version}/map-info-objects/{id}</pre>

=== Map Note ===
; Read
<pre>GET {api_url}/{version}/map-notes/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-notes</pre>
; Create
<pre>POST {api_url}/{version}/map-notes</pre>
; Update
<pre>PATCH {api_url}/{version}/map-notes/{id}</pre>

=== Map Permit ===
; Read
<pre>GET {api_url}/{version}/map-permits/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-permits</pre>
; Create
<pre>POST {api_url}/{version}/map-permits</pre>
; Update
<pre>PATCH {api_url}/{version}/map-permits/{id}</pre>

Example:
<pre>PATCH https://api.veronetworks.com/v1/map-permits/30768</pre>

Request body:
<syntaxhighlight lang="json">
{
  "mapProjectId": "11572",
  "poly": [
    [
      { "lat": "37.129198", "lng": "-87.791584" },
      { "lat": "36.127619", "lng": "-88.790082" }
    ],
    [
      { "lat": "35.126390", "lng": "-89.792399" },
      { "lat": "35.124500", "lng": "-89.794000" }
    ]
  ]
}
</syntaxhighlight>

=== Map Pole ===
; Read
<pre>GET {api_url}/{version}/map-poles/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-poles</pre>
; Create
<pre>POST {api_url}/{version}/map-poles</pre>
; Update
<pre>PATCH {api_url}/{version}/map-poles/{id}</pre>

=== Map Segment ===
; Read
<pre>GET {api_url}/{version}/map-segments/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-segments</pre>
; Create
<pre>POST {api_url}/{version}/map-segments</pre>
; Update
<pre>PATCH {api_url}/{version}/map-segments/{id}</pre>

Example:
<pre>PATCH https://api.veronetworks.com/v1/map-segments/1177</pre>

Request body:
<syntaxhighlight lang="json">
{
  "mapProjectId": 41,
  "poly": [
    { "lat": 32.7714169834758, "lng": -96.12168230422975 },
    { "lat": 32.77138, "lng": -97.12287 },
    { "lat": 32.770140000000005, "lng": -97.12288000000001 },
    { "lat": 32.77015, "lng": -97.1213 },
    { "lat": 32.77013598463115, "lng": -97.11901284516131 },
    { "lat": 32.769634804144374, "lng": -97.11900020370484 }
  ]
}
</syntaxhighlight>

=== Map Site ===
; Read
<pre>GET {api_url}/{version}/map-sites/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-sites</pre>
; Create
<pre>POST {api_url}/{version}/map-sites</pre>
; Update
<pre>PATCH {api_url}/{version}/map-sites/{id}</pre>

=== Map Splice ===
; Read
<pre>GET {api_url}/{version}/map-splices/{id}</pre>
; Read All
<pre>GET {api_url}/{version}/map-splices</pre>
; Create
<pre>POST {api_url}/{version}/map-splices</pre>
; Update
<pre>PATCH {api_url}/{version}/map-splices/{id}</pre>

----

== Expanding Tags ==

Some models support retrieving related tags directly in the response using the <code>expand</code> query parameter.

; Usage
<pre>GET {api_url}/{version}/{model}/{id}?expand=tags</pre>

This returns the base model plus its associated tags.  
Only models that extend <code>MapItem</code> and define the <code>tags</code> relation will support this.

Example:
<pre>GET https://api.veronetworks.com/v1/map-permit/9540?expand=tags</pre>

Response (snippet):
<syntaxhighlight lang="json">
{
  "id": 9540,
  "name": "Lower - Woodruff Rd S-417 (2) PH2",
  "tags": [
    { "id": 857, "name": "Lower", "mapprojectId": 216 }
  ]
}
</syntaxhighlight>

To expand multiple fields, separate them with commas.  
Example: <code>?expand=tags,owner</code>

----

== Filters ==

The Verofy API supports filters for refined queries via query parameters.

Example: filter map poles by <code>mapProjectId</code>
<pre>GET {api_url}/{version}/map-pole?filter%5BmapProjectId%5D=38</pre>

This retrieves all map poles associated with <code>mapProjectId=38</code>.

----


=== Get Effective Value ===
Retrieve the runtime value of a setting.
The API returns:

<code>value</code> (if set)

Otherwise <code>default_value</code>

Otherwise the fallback (if provided)

<pre>GET {api_url}/{version}/setting/value?name={settingName}&fallback={value}</pre>

Example:

<pre>GET https://api.veronetworks.com/v1/setting/value?name=mapping_tool.background_segment_width</pre>

Response:
<syntaxhighlight lang="json">
{
"name": "mapping_tool.background_segment_width",
"value": "5"
}
</syntaxhighlight>
== CRM Endpoints ==

=== Authentication ===
All CRM endpoints require an **API Key**.  
Include it in the <code>Authorization</code> header.

=== GET /v1/crm-vendors ===
; Description
Retrieve a list of CRM vendors.

; Request Example
<syntaxhighlight lang="bash">
curl -X GET "https://api.veronetworks.com/v1/crm-vendors" \
  -H "Authorization: YOUR-API-KEY"
</syntaxhighlight>

; Response Example
<syntaxhighlight lang="json">
{
  "items": [
    {
      "id": 1001,
      "name": "Vendor One",
      "email": "vendor1@example.com",
      "layout": "Standard",
      "primaryContactId": null,
      "backupContactId": null,
      "ownerId": 1
    },
    {
      "id": 1002,
      "name": "Vendor Two",
      "email": "vendor2@example.com",
      "layout": "Advanced",
      "primaryContactId": null,
      "backupContactId": null,
      "ownerId": 2
    }
  ],
  "_links": {
    "self":  { "href": "https://api.veronetworks.com/v1/crm-vendors?page=1" },
    "first": { "href": "https://api.veronetworks.com/v1/crm-vendors?page=1" },
    "last":  { "href": "https://api.veronetworks.com/v1/crm-vendors?page=10" },
    "next":  { "href": "https://api.veronetworks.com/v1/crm-vendors?page=2" }
  },
  "_meta": { "totalCount": 200, "pageCount": 10, "currentPage": 1, "perPage": 20 }
}
</syntaxhighlight>

=== List of Other CRM Endpoints ===
All follow the same authentication and response format.

; GET /v1/crm-contacts
Retrieve a list of CRM contacts.

; GET /v1/crm-accounts
Retrieve a list of CRM accounts.

; GET /v1/crm-services
Retrieve a list of CRM services.

; GET /v1/crm-capital-projects
Retrieve a list of CRM capital projects.

; GET /v1/crm-billing-items
Retrieve a list of CRM billing items.

----

== Notes ==
* All responses follow the same structure as <code>crm-vendors</code>.
* Pagination is supported with the <code>?page=N</code> query parameter.
* Replace <code>YOUR-API-KEY</code> in examples with a valid API key.