Projects

Update a project

Update a project using Ovok’s Slim API.

MethodPath
PUT/v1/slim/project/:id

Authentication · Access policies

Updates a project's name, address, contact and settings, and returns the updated project. Use it to edit your project or one of its child projects.

Auth: Bearer token of a project admin (ProjectMembership.admin). Scope: The project in the path. It must be the caller's project (from the token) or a direct child of it.

Request

Path parameters

NameTypeRequiredDescription
idstring (uuid)YesProject id. Your own project or a direct child of it.

Body

NameTypeRequiredDescription
namestringYesProject name. At least 1 character.
idstring (uuid)NoIgnored.
extensionanyNoIgnored.
addressobject[]NoPostal addresses. Omit to have none.
address[].use"work" | "temp" | "old" | "billing"NoPurpose of the address.
address[].type"postal" | "physical" | "both"NoKind of address.
address[].textstringNoThe address as one text.
address[].linestring[]NoStreet lines. Each is a non-empty string.
address[].citystringNoCity.
address[].districtstringNoDistrict.
address[].statestringNoState.
address[].postalCodestringNoPostal code.
address[].countrystringNoCountry.
contactobject[]NoContact persons. Omit to have none.
contact[].telecomobject[]NoWays to reach the contact.
contact[].telecom[].system"email" | "phone" | "fax" | "pager" | "url" | "sms" | "other"NoKind of contact point.
contact[].telecom[].use"work" | "temp" | "old" | "mobile"NoPurpose of the contact point.
contact[].telecom[].valuestringNoThe email address, phone number or URL.
contact[].nameobjectNoThe contact's name.
contact[].name.use"temp" | "old" | "official" | "usual" | "nickname" | "anonymous" | "maiden"NoKind of name.
contact[].name.prefixstring[]NoName prefixes.
contact[].name.givenstring[]NoGiven names.
contact[].name.familystringNoFamily name.
contact[].name.suffixstring[]NoName suffixes.
contact[].addressobjectNoThe contact's address, with the same fields as address[].
settingsobjectNoProject settings.
settings.timeZonestringNoTime zone name, such as Europe/Berlin. Default Europe/Berlin.
settings.trendsPeriodobjectNoThe daily window that trends cover. Omit to use the default.
settings.trendsPeriod.startstringYes, with settings.trendsPeriodStart time as HH:MM:SS.
settings.trendsPeriod.durationSecondsnumberYes, with settings.trendsPeriodLength of the window in seconds. 0 or more.

Behaviour

  • Sets the project name and replaces the organization stored inside the project with one built from name, address, contact and settings. This is a full replace, not a merge:
    • an omitted address or contact clears it;
    • an omitted settings.timeZone resets the time zone to Europe/Berlin;
    • an omitted settings.trendsPeriod removes the stored trends period, so reads fall back to the default.
  • id and extension in the body are ignored. The project comes from the path.
  • settings.trendsPeriod.start must be HH:MM:SS.
  • The response has the shape of GET /v1/slim/project/{id}.

Example

curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/project/b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example project",
    "address": [{ "line": ["Hauptstrasse 1"], "city": "Berlin", "postalCode": "10115", "country": "DE" }],
    "settings": { "timeZone": "Europe/Berlin", "trendsPeriod": { "start": "09:00:00", "durationSeconds": 86400 } }
  }'

Successful response

200 — The project was updated successfully.

{
  "resourceType": "Project",
  "id": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68",
  "name": "Example project",
  "address": [{ "line": ["Hauptstrasse 1"], "city": "Berlin", "postalCode": "10115", "country": "DE" }],
  "settings": { "timeZone": "Europe/Berlin", "trendsPeriod": { "start": "09:00:00", "durationSeconds": 86400 } }
}

The body is the updated project, as GET /v1/slim/project/{id} returns it.

FieldTypeDescription
resourceType"Project"Always Project.
idstring (uuid)Project id.
namestringProject name. The project id when the project has no name.
addressobject[]Postal addresses of the project. Left out when there are none. Each entry has the fields of address[] in the request: use, type, text, line, city, district, state, postalCode and country.
contactobject[]Contact persons of the project. Left out when there are none. Each entry has the fields of contact[] in the request: telecom, name and address.
settingsobjectProject settings.
settings.timeZonestringTime zone name. Europe/Berlin when none is stored.
settings.trendsPeriodobjectThe daily window that trends cover.
settings.trendsPeriod.startstringStart time as HH:MM:SS. 09:00:00 when none is stored.
settings.trendsPeriod.durationSecondsnumberLength of the window in seconds. 86400 when none is stored.

Errors

StatusMeaning
400The project is neither the caller's project nor a direct child of it, or it cannot be read.
401The bearer token is missing or invalid, or the session carries no project.
403The session is not a project admin session.
404No project has this id.
422id is not a UUID, or the body fails validation.

Last updated on

On this page