# Invitations

## Primary Driver Send Invitation to Secondary Driver

The SDK allows for the host application to enable the primary driver to send invitations to any secondary driver based on VEHICLE or FAMILY ACCOUNT.

### Concrete example

#### Sending invitation based on account

To send the invitation, the following API can be used.In this example we send an invitation based on ACCOUNT.

{% tabs %}
{% tab title="Swift" %}

```swift
let invitationService = InvitationService()
invitationService.sendAccountInvitation(fromUserID: fromUserID,
                                        toUserFirstName: toUserFirstName,
                                        toUserLastName: toUserLastName,
                                        toUserEmail: toUserEmail,
                                        toUserPhoneNumber: toUserPhoneNumber,
                                        fromAccountIds: fromAccountIDs, then: { result in
    switch result {
    case .success(_):
        // invitation successful
    case .failure
        // error
    }
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.sendAccountInvitation(fromUserId,
                              fromAccountIds,
                              toUserFirstName,
                              toUserLastName,
                              toUserPhoneNumber,
                              toUserEmail) { result: Result<List<Invitation>> ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val response = result.value
    }
})
```

{% endtab %}
{% endtabs %}

#### Sending invitation based on vehicle

To send the invitation based on VEHICLE you need to provide vehicleIds field instead of fromAccountIds and call sendVehicleInvitation.

{% tabs %}
{% tab title="Swift" %}

```swift
let invitationService = InvitationService()
invitationService.sendVehicleInvitation(fromUserID: fromUserID,
                                        toUserFirstName: toUserFirstName,
                                        toUserLastName: toUserLastName,
                                        toUserEmail: toUserEmail,
                                        toUserPhoneNumber: toUserPhoneNumber,
                                        vehicleIDs: vehicleIDs, then: { result in
    switch result {
    case .success(_):
        // invitation successful
    case .failure
        // error
    }
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.sendVehicleInvitation(fromUserId,
                                vehicleIds,
                                toUserFirstName,
                                toUserLastName,
                                toUserPhoneNumber,
                                toUserEmail){ result ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val response = result.value
        }
}
```

{% endtab %}
{% endtabs %}

## Remove secondary user from FAMILY ACCOUNT

The guest driver can be removed from the Family Account.

#### Removing secondary user based on account

To remove secondary guest driver based on account, the following API can be used.

### Concrete example

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.removeGuestDriverFromAccount(toUserId: userID,
                                     accountId: accountID, then: { result in
    switch result {
    case .success(_):
        // successfully removed
    case .failure
        // error
    }
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.removeDriverFromAccount(userId,
                                accountId) { result ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val response = result.value
        }
}
```

{% endtab %}
{% endtabs %}

#### Removing secondary user based on vehicle

To remove secondary guest driver based on vehicle, the following API can be used.

### Concrete example

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.removeGuestDriverFromVehicle(toUserId: userID,
                                     vehicleId: vehicle, then: { result in
    switch result {
    case .success(_):
        // successfully removed
    case .failure
        // error
    }
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.removeDriverFromVehicle(userId,
                                vehicleId){ result ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val response = result.value
        }
}
```

{% endtab %}
{% endtabs %}

## Retrieve Pending Invitations

The host application can retrieve pending invitations. The list contains all invitations that the user has sent or received, so apps should check the primaryDriver and secondaryDriver ID's to see if the current user sent (primary) or received (secondary) each one.

#### Pending Account Invitations

To retrieve the pending account invitations, the following API can be used.

### Concrete example

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.fetchAccountInvites(then: { result in
    guard !result.value?.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.fetchInvitations(userId) { result: Result<InvitationResponse?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val response = result.value
    }
})
```

{% endtab %}
{% endtabs %}

#### Pending vehicle Invitations

To retrieve pending vehicle invites, the following API can be used.

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.fetchVehicleInvites(then: { result in
    guard !result.value?.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.fetchVehicleInvitations(userId) { result: Result<InvitationResponse?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val response = result.value
    }
})
```

{% endtab %}
{% endtabs %}

## Respond to Pending Invitation

The host application can accept or decline pending invitations.

#### Accepting an invitation

To accept an invitation, the following API can be used.

### Concrete example

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.respondToInvitation(toUserId: toUserId,
                            invitationId: invitationId,
                            response: .accept, then: { result in
    switch result
    case .success(_):
        // response successful
    case .failure(_):
        // error
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.respondInvitation(invitation,
                          Invitation.Response.ACCEPT) { result: Result<Any> ->
    if (result.throwable != null) {
        // failure
    } else {
        // Success
        val response = result.value
    }
})
```

{% endtab %}
{% endtabs %}

#### Declining an invitation

To decline an invitation, the following API can be used.

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.respondToInvitation(toUserId: toUserId,
                            invitationId: invitationId,
                            response: .decline, then: { result in
    switch result
    case .success(_):
        // response successful
    case .failure(_):
        // error
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.respondInvitation(invitation,
                          Invitation.Response.DECLINE) { result: Result<Any> ->
    if (result.throwable != null) {
        // failure
    } else {
        // Success
        val response = result.value
    }
})
```

{% endtab %}
{% endtabs %}

## Cancel Pending Invitation

The host application can cancel pending invitations.

### Required information

* UserId: Only the user who sent the invitation can cancel it.

To cancel to an invitation, the following API can be used.

### Concrete example

{% tabs %}
{% tab title="Swift" %}

```swift
let service = InvitationService()
service.cancelVehicleInvitation(fromUserId: fromUserId,
                                invitationId: invitationId,
                                then: { result in
    switch result
    case .success(_):
        // cancel successful
    case .failure(_):
        // error
})
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val service = InvitationService()
service.cancelInvitation(invitation) { result: Result<Any> ->
    if (result.throwable != null) {
        // failure
    } else {
        // Success
        val response = result.value        
    }
})
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdk.ims.tech/drivesync-portal/invitations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.